bopodev-api 0.1.24 → 0.1.26

package/src/services/heartbeat-service.ts

@@ -1,24 +1,33 @@
 import { mkdir } from "node:fs/promises";
-import { resolve } from "node:path";
+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 { AgentState, HeartbeatContext } from "bopodev-agent-sdk";
 import {
+  type AgentFinalRunOutput,
   ControlPlaneHeadersJsonSchema,
   ControlPlaneRequestHeadersSchema,
   ControlPlaneRuntimeEnvSchema,
   ExecutionOutcomeSchema,
-  type ExecutionOutcome
+  type ExecutionOutcome,
+  type RunArtifact,
+  type RunCompletionReason,
+  type RunCompletionReport,
+  type RunCostSummary
 } from "bopodev-contracts";
 import type { BopoDb } from "bopodev-db";
 import {
+  addIssueComment,
+  approvalRequests,
   agents,
   appendActivity,
   appendHeartbeatRunMessages,
   companies,
+  createApprovalRequest,
   goals,
   heartbeatRuns,
+  issueComments,
   issueAttachments,
   issues,
   projects
@@ -26,12 +35,18 @@ import {
 import { appendAuditEvent, appendCost } from "bopodev-db";
 import { parseRuntimeConfigFromAgentRow } from "../lib/agent-config";
 import { bootstrapRepositoryWorkspace, ensureIsolatedGitWorktree, GitRuntimeError } from "../lib/git-runtime";
-import { isInsidePath, normalizeCompanyWorkspacePath, resolveProjectWorkspacePath } from "../lib/instance-paths";
+import {
+  isInsidePath,
+  normalizeCompanyWorkspacePath,
+  resolveCompanyWorkspaceRootPath,
+  resolveProjectWorkspacePath
+} from "../lib/instance-paths";
 import { assertRuntimeCwdForCompany, getProjectWorkspaceContextMap, hasText, resolveAgentFallbackWorkspace } from "../lib/workspace-policy";
 import type { RealtimeHub } from "../realtime/hub";
 import { createHeartbeatRunsRealtimeEvent } from "../realtime/heartbeat-runs";
+import { publishAttentionSnapshot } from "../realtime/attention";
 import { publishOfficeOccupantForAgent } from "../realtime/office-space";
-import { checkAgentBudget } from "./budget-service";
+import { appendProjectBudgetUsage, checkAgentBudget, checkProjectBudget } from "./budget-service";
 import { appendDurableFact, loadAgentMemoryContext, persistHeartbeatMemory } from "./memory-file-service";
 import { calculateModelPricedUsdCost } from "./model-pricing";
 import { runPluginHook } from "./plugin-runtime";
@@ -59,6 +74,47 @@ type ActiveHeartbeatRun = {
 };
 
 const activeHeartbeatRuns = new Map<string, ActiveHeartbeatRun>();
+type HeartbeatWakeContext = {
+  reason?: string | null;
+  commentId?: string | null;
+  commentBody?: string | null;
+  issueIds?: string[];
+};
+
+const AGENT_COMMENT_EMOJI_REGEX = /[\p{Extended_Pictographic}\uFE0F\u200D]/gu;
+
+type RunDigestSignal = {
+  sequence: number;
+  kind: "system" | "assistant" | "thinking" | "tool_call" | "tool_result" | "result" | "stderr";
+  label: string | null;
+  text: string | null;
+  payload: string | null;
+  signalLevel: "high" | "medium" | "low" | "noise";
+  groupKey: string | null;
+  source: "stdout" | "stderr" | "trace_fallback";
+};
+
+type RunDigest = {
+  status: "completed" | "failed" | "skipped";
+  headline: string;
+  summary: string;
+  successes: string[];
+  failures: string[];
+  blockers: string[];
+  nextAction: string;
+  evidence: {
+    transcriptSignalCount: number;
+    outcomeActionCount: number;
+    outcomeBlockerCount: number;
+    failureType: string | null;
+  };
+};
+
+type RunTerminalPresentation = {
+  internalStatus: "completed" | "failed" | "skipped";
+  publicStatus: "completed" | "failed";
+  completionReason: RunCompletionReason;
+};
 
 export async function claimIssuesForAgent(
   db: BopoDb,
@@ -75,7 +131,15 @@ export async function claimIssuesForAgent(
         AND assignee_agent_id = ${agentId}
         AND status IN ('todo', 'in_progress')
         AND is_claimed = false
-      ORDER BY updated_at ASC
+      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
     )
@@ -85,12 +149,13 @@ export async function claimIssuesForAgent(
         updated_at = CURRENT_TIMESTAMP
     FROM candidate c
     WHERE i.id = c.id
-    RETURNING i.id, i.project_id, i.title, i.body, i.status, i.priority, i.labels_json, i.tags_json;
+    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<{
     id: string;
     project_id: string;
+    parent_issue_id: string | null;
     title: string;
     body: string | null;
     status: string;
@@ -193,6 +258,50 @@ export async function stopHeartbeatRun(
   return { ok: true as const, runId, agentId: run.agentId, status: run.status };
 }
 
+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);
+}
+
 export async function runHeartbeatForAgent(
   db: BopoDb,
   companyId: string,
@@ -203,6 +312,7 @@ export async function runHeartbeatForAgent(
     realtimeHub?: RealtimeHub;
     mode?: HeartbeatRunMode;
     sourceRunId?: string;
+    wakeContext?: HeartbeatWakeContext;
   }
 ) {
   const runMode = options?.mode ?? "default";
@@ -250,6 +360,128 @@ export async function runHeartbeatForAgent(
 
   const budgetCheck = await checkAgentBudget(db, companyId, agentId);
   const runId = nanoid(14);
+  let blockedProjectBudgetChecks: Array<{ projectId: string; utilizationPct: number; monthlyBudgetUsd: number; usedBudgetUsd: number }> =
+    [];
+  if (budgetCheck.allowed) {
+    const projectIds = await loadProjectIdsForRunBudgetCheck(db, companyId, agentId, options?.wakeContext);
+    const projectChecks = await Promise.all(projectIds.map((projectId) => checkProjectBudget(db, companyId, projectId)));
+    blockedProjectBudgetChecks = projectChecks
+      .filter((entry) => entry.hardStopped)
+      .map((entry) => ({
+        projectId: entry.projectId,
+        utilizationPct: entry.utilizationPct,
+        monthlyBudgetUsd: entry.monthlyBudgetUsd,
+        usedBudgetUsd: entry.usedBudgetUsd
+      }));
+  }
+  if (blockedProjectBudgetChecks.length > 0) {
+    const blockedProjectIds = blockedProjectBudgetChecks.map((entry) => entry.projectId);
+    const message = `Heartbeat skipped due to project budget hard-stop: ${blockedProjectIds.join(",")}.`;
+    const runDigest = buildRunDigest({
+      status: "skipped",
+      executionSummary: message,
+      outcome: null,
+      trace: null,
+      signals: []
+    });
+    const runReport = buildRunCompletionReport({
+      companyId,
+      agentName: agent.name,
+      providerType: agent.providerType as HeartbeatProviderType,
+      issueIds: [],
+      executionSummary: message,
+      outcome: null,
+      trace: null,
+      digest: runDigest,
+      terminal: resolveRunTerminalPresentation({
+        internalStatus: "skipped",
+        executionSummary: message,
+        outcome: null,
+        trace: null
+      }),
+      cost: buildRunCostSummary({
+        tokenInput: 0,
+        tokenOutput: 0,
+        usdCost: null,
+        usdCostStatus: "unknown",
+        pricingSource: null,
+        source: "none"
+      })
+    });
+    const runListMessage = buildRunListMessageFromReport(runReport);
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      status: "skipped",
+      finishedAt: new Date(),
+      message: runListMessage
+    });
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "skipped",
+      message: runListMessage,
+      finishedAt: new Date()
+    });
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.failed",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: {
+        agentId,
+        issueIds: [],
+        result: runReport.resultSummary,
+        message: runListMessage,
+        errorType: runReport.completionReason,
+        errorMessage: message,
+        report: runReport,
+        outcome: null,
+        usage: {
+          tokenInput: 0,
+          tokenOutput: 0,
+          usdCostStatus: "unknown",
+          source: "none"
+        },
+        trace: null,
+        diagnostics: {
+          requestId: options?.requestId,
+          trigger: runTrigger
+        }
+      }
+    });
+    for (const blockedProject of blockedProjectBudgetChecks) {
+      const approvalId = await ensureProjectBudgetOverrideApprovalRequest(db, {
+        companyId,
+        projectId: blockedProject.projectId,
+        utilizationPct: blockedProject.utilizationPct,
+        monthlyBudgetUsd: blockedProject.monthlyBudgetUsd,
+        usedBudgetUsd: blockedProject.usedBudgetUsd,
+        runId
+      });
+      if (approvalId && options?.realtimeHub) {
+        await publishAttentionSnapshot(db, options.realtimeHub, companyId);
+      }
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "project_budget.hard_stop",
+        entityType: "project",
+        entityId: blockedProject.projectId,
+        payload: {
+          utilizationPct: blockedProject.utilizationPct,
+          monthlyBudgetUsd: blockedProject.monthlyBudgetUsd,
+          usedBudgetUsd: blockedProject.usedBudgetUsd,
+          runId
+        }
+      });
+    }
+    await publishOfficeOccupantForAgent(db, options?.realtimeHub, companyId, agentId);
+    return runId;
+  }
   if (budgetCheck.allowed) {
     const claimed = await insertStartedRunAtomic(db, {
       id: runId,
@@ -260,45 +492,156 @@ export async function runHeartbeatForAgent(
     if (!claimed) {
       const skippedRunId = nanoid(14);
       const skippedAt = new Date();
+      const overlapMessage = "Heartbeat skipped: another run is already in progress for this agent.";
+      const runDigest = buildRunDigest({
+        status: "skipped",
+        executionSummary: overlapMessage,
+        outcome: null,
+        trace: null,
+        signals: []
+      });
+      const runReport = buildRunCompletionReport({
+        companyId,
+        agentName: agent.name,
+        providerType: agent.providerType as HeartbeatProviderType,
+        issueIds: [],
+        executionSummary: overlapMessage,
+        outcome: null,
+        trace: null,
+        digest: runDigest,
+        terminal: resolveRunTerminalPresentation({
+          internalStatus: "skipped",
+          executionSummary: overlapMessage,
+          outcome: null,
+          trace: null
+        }),
+        cost: buildRunCostSummary({
+          tokenInput: 0,
+          tokenOutput: 0,
+          usdCost: null,
+          usdCostStatus: "unknown",
+          pricingSource: null,
+          source: "none"
+        })
+      });
+      const runListMessage = buildRunListMessageFromReport(runReport);
       await db.insert(heartbeatRuns).values({
         id: skippedRunId,
         companyId,
         agentId,
         status: "skipped",
         finishedAt: skippedAt,
-        message: "Heartbeat skipped: another run is already in progress for this agent."
+        message: runListMessage
       });
       publishHeartbeatRunStatus(options?.realtimeHub, {
         companyId,
         runId: skippedRunId,
         status: "skipped",
-        message: "Heartbeat skipped: another run is already in progress for this agent.",
+        message: runListMessage,
         finishedAt: skippedAt
       });
       await appendAuditEvent(db, {
         companyId,
         actorType: "system",
-        eventType: "heartbeat.skipped_overlap",
+        eventType: "heartbeat.failed",
         entityType: "heartbeat_run",
         entityId: skippedRunId,
         correlationId: options?.requestId ?? skippedRunId,
-        payload: { agentId, requestId: options?.requestId, trigger: runTrigger }
+        payload: {
+          agentId,
+          issueIds: [],
+          result: runReport.resultSummary,
+          message: runListMessage,
+          errorType: runReport.completionReason,
+          errorMessage: overlapMessage,
+          report: runReport,
+          outcome: null,
+          usage: {
+            tokenInput: 0,
+            tokenOutput: 0,
+            usdCostStatus: "unknown",
+            source: "none"
+          },
+          trace: null,
+          diagnostics: { requestId: options?.requestId, trigger: runTrigger }
+        }
       });
       return skippedRunId;
     }
   } else {
+    const budgetMessage = "Heartbeat skipped due to budget hard-stop.";
+    const runDigest = buildRunDigest({
+      status: "skipped",
+      executionSummary: budgetMessage,
+      outcome: null,
+      trace: null,
+      signals: []
+    });
+    const runReport = buildRunCompletionReport({
+      companyId,
+      agentName: agent.name,
+      providerType: agent.providerType as HeartbeatProviderType,
+      issueIds: [],
+      executionSummary: budgetMessage,
+      outcome: null,
+      trace: null,
+      digest: runDigest,
+      terminal: resolveRunTerminalPresentation({
+        internalStatus: "skipped",
+        executionSummary: budgetMessage,
+        outcome: null,
+        trace: null
+      }),
+      cost: buildRunCostSummary({
+        tokenInput: 0,
+        tokenOutput: 0,
+        usdCost: null,
+        usdCostStatus: "unknown",
+        pricingSource: null,
+        source: "none"
+      })
+    });
+    const runListMessage = buildRunListMessageFromReport(runReport);
     await db.insert(heartbeatRuns).values({
       id: runId,
       companyId,
       agentId,
       status: "skipped",
-      message: "Heartbeat skipped due to budget hard-stop."
+      finishedAt: new Date(),
+      message: runListMessage
     });
     publishHeartbeatRunStatus(options?.realtimeHub, {
       companyId,
       runId,
       status: "skipped",
-      message: "Heartbeat skipped due to budget hard-stop."
+      message: runListMessage,
+      finishedAt: new Date()
+    });
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.failed",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: {
+        agentId,
+        issueIds: [],
+        result: runReport.resultSummary,
+        message: runListMessage,
+        errorType: runReport.completionReason,
+        errorMessage: budgetMessage,
+        report: runReport,
+        outcome: null,
+        usage: {
+          tokenInput: 0,
+          tokenOutput: 0,
+          usdCostStatus: "unknown",
+          source: "none"
+        },
+        trace: null,
+        diagnostics: { requestId: options?.requestId, trigger: runTrigger }
+      }
     });
   }
 
@@ -315,7 +658,8 @@ export async function runHeartbeatForAgent(
         requestId: options?.requestId ?? null,
         trigger: runTrigger,
         mode: runMode,
-        sourceRunId: options?.sourceRunId ?? null
+        sourceRunId: options?.sourceRunId ?? null,
+        wakeContext: options?.wakeContext ?? null
       }
     });
     publishHeartbeatRunStatus(options?.realtimeHub, {
@@ -327,6 +671,17 @@ export async function runHeartbeatForAgent(
   }
 
   if (!budgetCheck.allowed) {
+    const approvalId = await ensureBudgetOverrideApprovalRequest(db, {
+      companyId,
+      agentId,
+      utilizationPct: budgetCheck.utilizationPct,
+      usedBudgetUsd: Number(agent.usedBudgetUsd),
+      monthlyBudgetUsd: Number(agent.monthlyBudgetUsd),
+      runId
+    });
+    if (approvalId && options?.realtimeHub) {
+      await publishAttentionSnapshot(db, options.realtimeHub, companyId);
+    }
     await appendAuditEvent(db, {
       companyId,
       actorType: "system",
@@ -351,6 +706,8 @@ export async function runHeartbeatForAgent(
   }
 
   let issueIds: string[] = [];
+  let claimedIssueIds: string[] = [];
+  let executionWorkItemsForBudget: Array<{ issueId: string; projectId: string }> = [];
   let state: AgentState & {
     runtime?: {
       command?: string;
@@ -378,6 +735,13 @@ export async function runHeartbeatForAgent(
   let runtimeLaunchSummary: ReturnType<typeof summarizeRuntimeLaunch> | null = null;
   let primaryIssueId: string | null = null;
   let primaryProjectId: string | null = null;
+  let providerUsageLimitDisposition:
+    | {
+        message: string;
+        notifyBoard: boolean;
+        pauseAgent: boolean;
+      }
+    | null = null;
   let transcriptSequence = 0;
   let transcriptWriteQueue = Promise.resolve();
   let transcriptLiveCount = 0;
@@ -386,6 +750,7 @@ export async function runHeartbeatForAgent(
   let transcriptPersistFailureReported = false;
   let pluginFailureSummary: string[] = [];
   const seenResultMessages = new Set<string>();
+  const runDigestSignals: RunDigestSignal[] = [];
 
   const enqueueTranscriptEvent = (event: {
     kind: string;
@@ -413,6 +778,21 @@ export async function runHeartbeatForAgent(
     if (signalLevel === "high") {
       transcriptLiveHighSignalCount += 1;
     }
+    if (isUsefulTranscriptSignal(signalLevel)) {
+      runDigestSignals.push({
+        sequence,
+        kind: normalizeTranscriptKind(event.kind),
+        label: event.label ?? null,
+        text: event.text ?? null,
+        payload: event.payload ?? null,
+        signalLevel,
+        groupKey: groupKey ?? null,
+        source
+      });
+      if (runDigestSignals.length > 200) {
+        runDigestSignals.splice(0, runDigestSignals.length - 200);
+      }
+    }
     transcriptWriteQueue = transcriptWriteQueue
       .then(async () => {
         await appendHeartbeatRunMessages(db, {
@@ -511,10 +891,16 @@ export async function runHeartbeatForAgent(
       },
       failClosed: false
     });
-    const workItems = await claimIssuesForAgent(db, companyId, agentId, runId);
-    issueIds = workItems.map((item) => item.id);
-    primaryIssueId = workItems[0]?.id ?? null;
-    primaryProjectId = workItems[0]?.project_id ?? null;
+    const isCommentOrderWake = options?.wakeContext?.reason === "issue_comment_recipient";
+    const workItems = isCommentOrderWake ? [] : await claimIssuesForAgent(db, companyId, agentId, runId);
+    const wakeWorkItems = await loadWakeContextWorkItems(db, companyId, options?.wakeContext?.issueIds);
+    const contextWorkItems = resolveExecutionWorkItems(workItems, wakeWorkItems, options?.wakeContext);
+    executionWorkItemsForBudget = contextWorkItems.map((item) => ({ issueId: item.id, projectId: item.project_id }));
+    claimedIssueIds = workItems.map((item) => item.id);
+    issueIds = contextWorkItems.map((item) => item.id);
+    primaryIssueId = contextWorkItems[0]?.id ?? null;
+    primaryProjectId = contextWorkItems[0]?.project_id ?? null;
+    const resolvedWakeContext = await resolveHeartbeatWakeContext(db, companyId, options?.wakeContext);
     await runPluginHook(db, {
       hook: "afterClaim",
       context: {
@@ -523,7 +909,7 @@ export async function runHeartbeatForAgent(
         runId,
         requestId: options?.requestId,
         providerType: agent.providerType,
-        workItemCount: workItems.length
+        workItemCount: contextWorkItems.length
       },
       failClosed: false
     });
@@ -539,7 +925,8 @@ export async function runHeartbeatForAgent(
       companyId,
       agentId: agent.id,
       heartbeatRunId: runId,
-      canHireAgents: agent.canHireAgents
+      canHireAgents: agent.canHireAgents,
+      wakeContext: options?.wakeContext
     });
     const runtimeFromConfig = {
       command: persistedRuntime.runtimeCommand,
@@ -580,18 +967,13 @@ export async function runHeartbeatForAgent(
       db,
       companyId,
       agent.id,
-      workItems,
+      contextWorkItems,
       mergedRuntime
     );
     state = {
       ...state,
       runtime: workspaceResolution.runtime
     };
-    memoryContext = await loadAgentMemoryContext({
-      companyId,
-      agentId
-    });
-
     let context = await buildHeartbeatContext(db, companyId, {
       agentId,
       agentName: agent.name,
@@ -602,8 +984,27 @@ export async function runHeartbeatForAgent(
       state,
       memoryContext,
       runtime: workspaceResolution.runtime,
-      workItems
+      workItems: contextWorkItems,
+      wakeContext: resolvedWakeContext
+    });
+    const memoryQueryText = [
+      context.company.mission ?? "",
+      ...(context.goalContext?.companyGoals ?? []),
+      ...(context.goalContext?.projectGoals ?? []),
+      ...context.workItems.map((item) => `${item.title} ${item.body ?? ""}`)
+    ]
+      .join(" ")
+      .trim();
+    memoryContext = await loadAgentMemoryContext({
+      companyId,
+      agentId,
+      projectIds: context.workItems.map((item) => item.projectId),
+      queryText: memoryQueryText
     });
+    context = {
+      ...context,
+      memoryContext
+    };
     if (workspaceResolution.warnings.length > 0) {
       await appendAuditEvent(db, {
         companyId,
@@ -663,7 +1064,7 @@ export async function runHeartbeatForAgent(
       resolveControlPlanePreflightEnabled() &&
       shouldRequireControlPlanePreflight(
         agent.providerType as HeartbeatProviderType,
-        workItems.length
+        contextWorkItems.length
       )
     ) {
       const preflight = await runControlPlaneConnectivityPreflight({
@@ -743,7 +1144,7 @@ export async function runHeartbeatForAgent(
         runId,
         requestId: options?.requestId,
         providerType: agent.providerType,
-        workItemCount: workItems.length,
+        workItemCount: contextWorkItems.length,
         runtime: {
           command: workspaceResolution.runtime.command,
           cwd: workspaceResolution.runtime.cwd
@@ -782,7 +1183,20 @@ export async function runHeartbeatForAgent(
       runtime: workspaceResolution.runtime,
       externalAbortSignal: activeRunAbort.signal
     });
-    executionSummary = execution.summary;
+    const usageLimitHint = execution.dispositionHint?.kind === "provider_usage_limited" ? execution.dispositionHint : null;
+    if (usageLimitHint) {
+      providerUsageLimitDisposition = {
+        message: usageLimitHint.message,
+        notifyBoard: usageLimitHint.notifyBoard,
+        pauseAgent: usageLimitHint.pauseAgent
+      };
+    }
+    executionSummary =
+      usageLimitHint?.message && usageLimitHint.message.trim().length > 0 ? usageLimitHint.message.trim() : execution.summary;
+    executionSummary = sanitizeAgentSummaryCommentBody(extractNaturalRunUpdate(executionSummary));
+    const persistedExecutionStatus: "ok" | "failed" | "skipped" = usageLimitHint ? "skipped" : execution.status;
+    const persistedRunStatus: "completed" | "failed" | "skipped" =
+      persistedExecutionStatus === "ok" ? "completed" : persistedExecutionStatus;
     const normalizedUsage = execution.usage ?? {
       inputTokens: Math.max(0, execution.tokenInput),
       cachedInputTokens: 0,
@@ -811,7 +1225,6 @@ export async function runHeartbeatForAgent(
     if (afterAdapterHook.failures.length > 0) {
       pluginFailureSummary = [...pluginFailureSummary, ...afterAdapterHook.failures];
     }
-    emitCanonicalResultEvent(executionSummary, "completed");
     executionTrace = execution.trace ?? null;
     const runtimeModelId = resolveRuntimeModelId({
       runtimeModel: persistedRuntime.runtimeModel,
@@ -822,6 +1235,7 @@ export async function runHeartbeatForAgent(
     const costDecision = await appendFinishedRunCostEntry({
       db,
       companyId,
+      runId,
       providerType: agent.providerType,
       runtimeModelId: effectivePricingModelId ?? runtimeModelId,
       pricingProviderType: effectivePricingProviderType,
@@ -833,18 +1247,27 @@ export async function runHeartbeatForAgent(
       issueId: primaryIssueId,
       projectId: primaryProjectId,
       agentId,
-      status: execution.status
+      status: persistedExecutionStatus
     });
     const executionUsdCost = costDecision.usdCost;
+    await appendProjectBudgetUsage(db, {
+      companyId,
+      projectCostsUsd: buildProjectBudgetCostAllocations(executionWorkItemsForBudget, executionUsdCost)
+    });
     const parsedOutcome = ExecutionOutcomeSchema.safeParse(execution.outcome);
     executionOutcome = parsedOutcome.success ? parsedOutcome.data : null;
     const persistedMemory = await persistHeartbeatMemory({
       companyId,
       agentId,
       runId,
-      status: execution.status,
-      summary: execution.summary,
-      outcomeKind: executionOutcome?.kind ?? null
+      status: persistedExecutionStatus === "ok" ? "ok" : "failed",
+      summary: executionSummary,
+      outcomeKind: executionOutcome?.kind ?? null,
+      mission: context.company.mission ?? null,
+      goalContext: {
+        companyGoals: context.goalContext?.companyGoals ?? [],
+        projectGoals: context.goalContext?.projectGoals ?? []
+      }
     });
     await appendAuditEvent(db, {
       companyId,
@@ -860,7 +1283,7 @@ export async function runHeartbeatForAgent(
         candidateFacts: persistedMemory.candidateFacts
       }
     });
-    if (execution.status === "ok") {
+    if (execution.status === "ok" && !usageLimitHint) {
       for (const fact of persistedMemory.candidateFacts) {
         const targetFile = await appendDurableFact({
           companyId,
@@ -883,13 +1306,33 @@ export async function runHeartbeatForAgent(
         });
       }
     }
+    const missionAlignment = computeMissionAlignmentSignal({
+      summary: executionSummary,
+      mission: context.company.mission ?? null,
+      companyGoals: context.goalContext?.companyGoals ?? [],
+      projectGoals: context.goalContext?.projectGoals ?? []
+    });
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.memory_alignment_scored",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: {
+        agentId,
+        score: missionAlignment.score,
+        matchedMissionTerms: missionAlignment.matchedMissionTerms,
+        matchedGoalTerms: missionAlignment.matchedGoalTerms
+      }
+    });
 
     if (
       execution.nextState ||
       executionUsdCost > 0 ||
       effectiveTokenInput > 0 ||
       effectiveTokenOutput > 0 ||
-      execution.status !== "skipped"
+      persistedExecutionStatus !== "skipped"
     ) {
       await db
         .update(agents)
@@ -967,8 +1410,8 @@ export async function runHeartbeatForAgent(
         runId,
         requestId: options?.requestId,
         providerType: agent.providerType,
-        status: execution.status,
-        summary: execution.summary
+        status: persistedExecutionStatus,
+        summary: executionSummary
       },
       failClosed: false
     });
@@ -976,25 +1419,95 @@ export async function runHeartbeatForAgent(
       pluginFailureSummary = [...pluginFailureSummary, ...beforePersistHook.failures];
     }
 
+    const runDigest = buildRunDigest({
+      status: persistedRunStatus,
+      executionSummary,
+      outcome: executionOutcome,
+      trace: executionTrace,
+      signals: runDigestSignals
+    });
+    const terminalPresentation = resolveRunTerminalPresentation({
+      internalStatus: persistedRunStatus,
+      executionSummary,
+      outcome: executionOutcome,
+      trace: executionTrace
+    });
+    const runCost = buildRunCostSummary({
+      tokenInput: effectiveTokenInput,
+      tokenOutput: effectiveTokenOutput,
+      usdCost: costDecision.usdCostStatus === "unknown" ? null : executionUsdCost,
+      usdCostStatus: costDecision.usdCostStatus,
+      pricingSource: costDecision.pricingSource ?? null,
+      source: readTraceString(execution.trace, "usageSource") ?? "unknown"
+    });
+    const runReport = buildRunCompletionReport({
+      companyId,
+      agentName: agent.name,
+      providerType: agent.providerType as HeartbeatProviderType,
+      issueIds,
+      executionSummary,
+      outcome: executionOutcome,
+      finalRunOutput: execution.finalRunOutput ?? null,
+      trace: executionTrace,
+      digest: runDigest,
+      terminal: terminalPresentation,
+      cost: runCost,
+      runtimeCwd: workspaceResolution.runtime.cwd
+    });
+    emitCanonicalResultEvent(runReport.resultSummary, runReport.finalStatus);
+    const runListMessage = buildRunListMessageFromReport(runReport);
     await db
       .update(heartbeatRuns)
       .set({
-        status: execution.status === "failed" ? "failed" : "completed",
+        status: persistedRunStatus,
         finishedAt: new Date(),
-        message: execution.summary
+        message: runListMessage
       })
       .where(eq(heartbeatRuns.id, runId));
     publishHeartbeatRunStatus(options?.realtimeHub, {
       companyId,
       runId,
-      status: execution.status === "failed" ? "failed" : "completed",
-      message: execution.summary,
+      status: persistedRunStatus,
+      message: runListMessage,
       finishedAt: new Date()
     });
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.run_digest",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: runDigest
+    });
+    try {
+      await appendRunSummaryComments(db, {
+        companyId,
+        issueIds,
+        agentId,
+        runId,
+        report: runReport
+      });
+    } catch (commentError) {
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.run_comment_failed",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          issueIds,
+          error: String(commentError)
+        }
+      });
+    }
 
     const fallbackMessages = normalizeTraceTranscript(executionTrace);
     const fallbackHighSignalCount = fallbackMessages.filter((message) => message.signalLevel === "high").length;
     const shouldAppendFallback =
+      !providerUsageLimitDisposition &&
       fallbackMessages.length > 0 &&
       (transcriptLiveCount === 0 ||
         transcriptLiveUsefulCount < 2 ||
@@ -1039,6 +1552,24 @@ export async function runHeartbeatForAgent(
         source: "trace_fallback",
         createdAt
       }));
+      for (const row of rows) {
+        if (!isUsefulTranscriptSignal(row.signalLevel)) {
+          continue;
+        }
+        runDigestSignals.push({
+          sequence: row.sequence,
+          kind: row.kind,
+          label: row.label,
+          text: row.text,
+          payload: row.payloadJson,
+          signalLevel: row.signalLevel,
+          groupKey: row.groupKey,
+          source: "trace_fallback"
+        });
+      }
+      if (runDigestSignals.length > 200) {
+        runDigestSignals.splice(0, runDigestSignals.length - 200);
+      }
       await appendHeartbeatRunMessages(db, {
         companyId,
         runId,
@@ -1073,8 +1604,8 @@ export async function runHeartbeatForAgent(
         runId,
         requestId: options?.requestId,
         providerType: agent.providerType,
-        status: execution.status,
-        summary: execution.summary,
+        status: persistedExecutionStatus,
+        summary: executionSummary,
         trace: executionTrace,
         outcome: executionOutcome
       },
@@ -1084,6 +1615,48 @@ export async function runHeartbeatForAgent(
       pluginFailureSummary = [...pluginFailureSummary, ...afterPersistHook.failures];
     }
 
+    if (providerUsageLimitDisposition) {
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.provider_usage_limited",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          providerType: agent.providerType,
+          issueIds,
+          message: providerUsageLimitDisposition.message
+        }
+      });
+      const pauseResult = providerUsageLimitDisposition.pauseAgent
+        ? await pauseAgentForProviderUsageLimit(db, {
+            companyId,
+            agentId,
+            requestId: options?.requestId ?? runId,
+            runId,
+            providerType: agent.providerType,
+            message: providerUsageLimitDisposition.message
+          })
+        : { paused: false };
+      if (providerUsageLimitDisposition.notifyBoard) {
+        await appendProviderUsageLimitBoardComments(db, {
+          companyId,
+          issueIds,
+          agentId,
+          runId,
+          providerType: agent.providerType,
+          message: providerUsageLimitDisposition.message,
+          paused: pauseResult.paused
+        });
+        if (options?.realtimeHub) {
+          await publishAttentionSnapshot(db, options.realtimeHub, companyId);
+        }
+      }
+      await publishOfficeOccupantForAgent(db, options?.realtimeHub, companyId, agentId);
+    }
+
     await appendAuditEvent(db, {
       companyId,
       actorType: "system",
@@ -1093,14 +1666,17 @@ export async function runHeartbeatForAgent(
       correlationId: options?.requestId ?? runId,
       payload: {
         agentId,
-        result: execution.summary,
-        message: execution.summary,
+        status: persistedRunStatus,
+        result: runReport.resultSummary,
+        message: runListMessage,
+        report: runReport,
         outcome: executionOutcome,
         issueIds,
         usage: {
           tokenInput: effectiveTokenInput,
           tokenOutput: effectiveTokenOutput,
           usdCost: executionUsdCost,
+          usdCostStatus: costDecision.usdCostStatus,
           source: readTraceString(execution.trace, "usageSource") ?? "unknown"
         },
         trace: execution.trace ?? null,
@@ -1160,13 +1736,41 @@ export async function runHeartbeatForAgent(
         cwd: runtimeLaunchSummary.cwd ?? null
       };
     }
+    try {
+      const failedMemory = await persistHeartbeatMemory({
+        companyId,
+        agentId,
+        runId,
+        status: "failed",
+        summary: executionSummary,
+        outcomeKind: executionOutcome?.kind ?? null
+      });
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.memory_updated",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          memoryRoot: failedMemory.memoryRoot,
+          dailyNotePath: failedMemory.dailyNotePath,
+          candidateFacts: failedMemory.candidateFacts,
+          failurePath: true
+        }
+      });
+    } catch {
+      // best effort; do not mask primary heartbeat failure.
+    }
     const runtimeModelId = resolveRuntimeModelId({
       runtimeModel: persistedRuntime.runtimeModel,
       stateBlob: agent.stateBlob
     });
-    await appendFinishedRunCostEntry({
+    const failureCostDecision = await appendFinishedRunCostEntry({
       db,
       companyId,
+      runId,
       providerType: agent.providerType,
       runtimeModelId,
       pricingProviderType: agent.providerType,
@@ -1178,21 +1782,96 @@ export async function runHeartbeatForAgent(
       agentId,
       status: "failed"
     });
-    await db
-      .update(heartbeatRuns)
-      .set({
-        status: "failed",
-        finishedAt: new Date(),
-        message: executionSummary
-      })
-      .where(eq(heartbeatRuns.id, runId));
-    publishHeartbeatRunStatus(options?.realtimeHub, {
+    await appendProjectBudgetUsage(db, {
       companyId,
-      runId,
+      projectCostsUsd: buildProjectBudgetCostAllocations(executionWorkItemsForBudget, failureCostDecision.usdCost)
+    });
+    const runDigest = buildRunDigest({
       status: "failed",
-      message: executionSummary,
-      finishedAt: new Date()
+      executionSummary,
+      outcome: executionOutcome,
+      trace: executionTrace,
+      signals: runDigestSignals
     });
+    const runCost = buildRunCostSummary({
+      tokenInput: 0,
+      tokenOutput: 0,
+      usdCost: failureCostDecision.usdCostStatus === "unknown" ? null : failureCostDecision.usdCost,
+      usdCostStatus: failureCostDecision.usdCostStatus,
+      pricingSource: failureCostDecision.pricingSource ?? null,
+      source: readTraceString(executionTrace, "usageSource") ?? "unknown"
+    });
+    const runReport = buildRunCompletionReport({
+      companyId,
+      agentName: agent.name,
+      providerType: agent.providerType as HeartbeatProviderType,
+      issueIds,
+      executionSummary,
+      outcome: executionOutcome,
+      finalRunOutput: null,
+      trace: executionTrace,
+      digest: runDigest,
+      terminal: resolveRunTerminalPresentation({
+        internalStatus: "failed",
+        executionSummary,
+        outcome: executionOutcome,
+        trace: executionTrace,
+        errorType: classified.type
+      }),
+      cost: runCost,
+      runtimeCwd: runtimeLaunchSummary?.cwd ?? persistedRuntime.runtimeCwd ?? null,
+      errorType: classified.type,
+      errorMessage: classified.message
+    });
+    const runListMessage = buildRunListMessageFromReport(runReport);
+    await db
+      .update(heartbeatRuns)
+      .set({
+        status: "failed",
+        finishedAt: new Date(),
+        message: runListMessage
+      })
+      .where(eq(heartbeatRuns.id, runId));
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "failed",
+      message: runListMessage,
+      finishedAt: new Date()
+    });
+    emitCanonicalResultEvent(runReport.resultSummary, runReport.finalStatus);
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.run_digest",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: runDigest
+    });
+    try {
+      await appendRunSummaryComments(db, {
+        companyId,
+        issueIds,
+        agentId,
+        runId,
+        report: runReport
+      });
+    } catch (commentError) {
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.run_comment_failed",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          issueIds,
+          error: String(commentError)
+        }
+      });
+    }
     await appendAuditEvent(db, {
       companyId,
       actorType: "system",
@@ -1203,12 +1882,17 @@ export async function runHeartbeatForAgent(
       payload: {
         agentId,
         issueIds,
-        result: executionSummary,
-        message: executionSummary,
+        result: runReport.resultSummary,
+        message: runListMessage,
         errorType: classified.type,
         errorMessage: classified.message,
+        report: runReport,
         outcome: executionOutcome,
         usage: {
+          tokenInput: 0,
+          tokenOutput: 0,
+          usdCost: failureCostDecision.usdCost,
+          usdCostStatus: failureCostDecision.usdCostStatus,
           source: readTraceString(executionTrace, "usageSource") ?? "unknown"
         },
         trace: executionTrace,
@@ -1240,7 +1924,7 @@ export async function runHeartbeatForAgent(
     await transcriptWriteQueue;
     unregisterActiveHeartbeatRun(runId);
     try {
-      await releaseClaimedIssues(db, companyId, issueIds);
+      await releaseClaimedIssues(db, companyId, claimedIssueIds);
     } catch (releaseError) {
       await appendAuditEvent(db, {
         companyId,
@@ -1251,12 +1935,21 @@ export async function runHeartbeatForAgent(
         correlationId: options?.requestId ?? runId,
         payload: {
           agentId,
-          issueIds,
+          issueIds: claimedIssueIds,
           error: String(releaseError)
         }
       });
     }
     await publishOfficeOccupantForAgent(db, options?.realtimeHub, companyId, agentId);
+    try {
+      const queueModule = await import("./heartbeat-queue-service");
+      queueModule.triggerHeartbeatQueueWorker(db, companyId, {
+        requestId: options?.requestId,
+        realtimeHub: options?.realtimeHub
+      });
+    } catch {
+      // Queue worker trigger is best-effort to keep heartbeat execution resilient.
+    }
   }
 
   return runId;
@@ -1332,230 +2025,1554 @@ async function recoverStaleHeartbeatRuns(
   }
 }
 
-export async function runHeartbeatSweep(
-  db: BopoDb,
-  companyId: string,
-  options?: { requestId?: string; realtimeHub?: RealtimeHub }
-) {
-  const companyAgents = await db.select().from(agents).where(eq(agents.companyId, companyId));
-  const recentRuns = await db
-    .select({ agentId: heartbeatRuns.agentId, startedAt: heartbeatRuns.startedAt })
-    .from(heartbeatRuns)
-    .where(eq(heartbeatRuns.companyId, companyId))
-    .orderBy(desc(heartbeatRuns.startedAt));
-  const latestRunByAgent = new Map<string, Date>();
-  for (const run of recentRuns) {
-    if (!latestRunByAgent.has(run.agentId)) {
-      latestRunByAgent.set(run.agentId, run.startedAt);
+export async function runHeartbeatSweep(
+  db: BopoDb,
+  companyId: string,
+  options?: { requestId?: string; realtimeHub?: RealtimeHub }
+) {
+  const companyAgents = await db.select().from(agents).where(eq(agents.companyId, companyId));
+  const latestRunByAgent = await listLatestRunByAgent(db, companyId);
+
+  const now = new Date();
+  const enqueuedJobIds: string[] = [];
+  const dueAgents: Array<{ id: string }> = [];
+  let skippedNotDue = 0;
+  let skippedStatus = 0;
+  let skippedBudgetBlocked = 0;
+  let failedStarts = 0;
+  const sweepStartedAt = Date.now();
+  for (const agent of companyAgents) {
+    if (agent.status !== "idle" && agent.status !== "running") {
+      skippedStatus += 1;
+      continue;
+    }
+    if (!isHeartbeatDue(agent.heartbeatCron, latestRunByAgent.get(agent.id) ?? null, now)) {
+      skippedNotDue += 1;
+      continue;
+    }
+    const blockedProjectIds = await findPendingProjectBudgetOverrideBlocksForAgent(db, companyId, agent.id);
+    if (blockedProjectIds.length > 0) {
+      skippedBudgetBlocked += 1;
+      continue;
+    }
+    dueAgents.push({ id: agent.id });
+  }
+  const sweepConcurrency = resolveHeartbeatSweepConcurrency(dueAgents.length);
+  const queueModule = await import("./heartbeat-queue-service");
+  await runWithConcurrency(dueAgents, sweepConcurrency, async (agent) => {
+    try {
+      const job = await queueModule.enqueueHeartbeatQueueJob(db, {
+        companyId,
+        agentId: agent.id,
+        jobType: "scheduler",
+        priority: 80,
+        idempotencyKey: options?.requestId ? `scheduler:${agent.id}:${options.requestId}` : null,
+        payload: {}
+      });
+      enqueuedJobIds.push(job.id);
+      queueModule.triggerHeartbeatQueueWorker(db, companyId, {
+        requestId: options?.requestId,
+        realtimeHub: options?.realtimeHub
+      });
+    } catch {
+      failedStarts += 1;
+    }
+  });
+  await appendAuditEvent(db, {
+    companyId,
+    actorType: "system",
+    eventType: "heartbeat.sweep.completed",
+    entityType: "company",
+    entityId: companyId,
+    correlationId: options?.requestId ?? null,
+    payload: {
+      runIds: enqueuedJobIds,
+      startedCount: enqueuedJobIds.length,
+      dueCount: dueAgents.length,
+      failedStarts,
+      skippedStatus,
+      skippedNotDue,
+      skippedBudgetBlocked,
+      concurrency: sweepConcurrency,
+      elapsedMs: Date.now() - sweepStartedAt,
+      requestId: options?.requestId ?? null
+    }
+  });
+  return enqueuedJobIds;
+}
+
+async function listLatestRunByAgent(db: BopoDb, companyId: string) {
+  const result = await db.execute(sql`
+    SELECT agent_id, MAX(started_at) AS latest_started_at
+    FROM heartbeat_runs
+    WHERE company_id = ${companyId}
+    GROUP BY agent_id
+  `);
+  const latestRunByAgent = new Map<string, Date>();
+  for (const row of result.rows ?? []) {
+    const agentId = typeof row.agent_id === "string" ? row.agent_id : null;
+    if (!agentId) {
+      continue;
+    }
+    const startedAt = coerceDate(row.latest_started_at);
+    if (!startedAt) {
+      continue;
+    }
+    latestRunByAgent.set(agentId, startedAt);
+  }
+  return latestRunByAgent;
+}
+
+function coerceDate(value: unknown) {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  }
+  return null;
+}
+
+async function loadWakeContextWorkItems(db: BopoDb, companyId: string, wakeIssueIds?: string[]) {
+  const normalizedIds = Array.from(new Set((wakeIssueIds ?? []).filter((id) => id.trim().length > 0)));
+  if (normalizedIds.length === 0) {
+    return [] 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;
+    }>;
+  }
+  const rows = await db
+    .select({
+      id: issues.id,
+      project_id: issues.projectId,
+      parent_issue_id: issues.parentIssueId,
+      title: issues.title,
+      body: issues.body,
+      status: issues.status,
+      priority: issues.priority,
+      labels_json: issues.labelsJson,
+      tags_json: issues.tagsJson
+    })
+    .from(issues)
+    .where(and(eq(issues.companyId, companyId), inArray(issues.id, normalizedIds)));
+  const sortOrder = new Map(normalizedIds.map((id, index) => [id, index]));
+  return rows.sort((a, b) => (sortOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (sortOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER));
+}
+
+function mergeContextWorkItems(
+  assigned: 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;
+  }>,
+  wakeContext: 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;
+  }>
+) {
+  const seen = new Set<string>();
+  const merged: typeof assigned = [];
+  for (const item of assigned) {
+    if (!seen.has(item.id)) {
+      seen.add(item.id);
+      merged.push(item);
+    }
+  }
+  for (const item of wakeContext) {
+    if (!seen.has(item.id)) {
+      seen.add(item.id);
+      merged.push(item);
+    }
+  }
+  return merged;
+}
+
+function resolveExecutionWorkItems(
+  assigned: 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;
+  }>,
+  wakeContextItems: 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;
+  }>,
+  wakeContext?: HeartbeatWakeContext
+) {
+  if (wakeContext?.reason === "issue_comment_recipient" && wakeContextItems.length > 0) {
+    return wakeContextItems;
+  }
+  return mergeContextWorkItems(assigned, wakeContextItems);
+}
+
+async function resolveHeartbeatWakeContext(
+  db: BopoDb,
+  companyId: string,
+  wakeContext?: HeartbeatWakeContext
+): Promise<HeartbeatWakeContext | undefined> {
+  if (!wakeContext) {
+    return undefined;
+  }
+  const commentBody = wakeContext.commentId
+    ? await loadWakeContextCommentBody(db, companyId, wakeContext.commentId)
+    : null;
+  return {
+    reason: wakeContext.reason ?? null,
+    commentId: wakeContext.commentId ?? null,
+    commentBody,
+    issueIds: wakeContext.issueIds ?? []
+  };
+}
+
+async function loadWakeContextCommentBody(db: BopoDb, companyId: string, commentId: string) {
+  const [comment] = await db
+    .select({ body: issueComments.body })
+    .from(issueComments)
+    .where(and(eq(issueComments.companyId, companyId), eq(issueComments.id, commentId)))
+    .limit(1);
+  const body = comment?.body?.trim();
+  return body && body.length > 0 ? body : null;
+}
+
+async function buildHeartbeatContext(
+  db: BopoDb,
+  companyId: string,
+  input: {
+    agentId: string;
+    agentName: string;
+    agentRole: string;
+    managerAgentId: string | null;
+    providerType: HeartbeatProviderType;
+    heartbeatRunId: string;
+    state: AgentState;
+    memoryContext?: HeartbeatContext["memoryContext"];
+    runtime?: { command?: string; args?: string[]; cwd?: string; timeoutMs?: number };
+    wakeContext?: HeartbeatWakeContext;
+    workItems: 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;
+    }>;
+  }
+): Promise<HeartbeatContext> {
+  const [company] = await db
+    .select({ name: companies.name, mission: companies.mission })
+    .from(companies)
+    .where(eq(companies.id, companyId))
+    .limit(1);
+  const projectIds = Array.from(new Set(input.workItems.map((item) => item.project_id)));
+  const projectRows =
+    projectIds.length > 0
+      ? await db
+          .select({ id: projects.id, name: projects.name })
+          .from(projects)
+          .where(and(eq(projects.companyId, companyId), inArray(projects.id, projectIds)))
+      : [];
+  const projectNameById = new Map(projectRows.map((row) => [row.id, row.name]));
+  const projectWorkspaceContextMap = await getProjectWorkspaceContextMap(db, companyId, projectIds);
+  const projectWorkspaceMap = new Map(
+    Array.from(projectWorkspaceContextMap.entries()).map(([projectId, context]) => [projectId, context.cwd])
+  );
+  const issueIds = input.workItems.map((item) => item.id);
+  const childIssueRows =
+    issueIds.length > 0
+      ? await db
+          .select({
+            id: issues.id,
+            parentIssueId: issues.parentIssueId
+          })
+          .from(issues)
+          .where(and(eq(issues.companyId, companyId), inArray(issues.parentIssueId, issueIds)))
+      : [];
+  const childIssueIdsByParent = new Map<string, string[]>();
+  for (const row of childIssueRows) {
+    if (!row.parentIssueId) {
+      continue;
+    }
+    const existing = childIssueIdsByParent.get(row.parentIssueId) ?? [];
+    existing.push(row.id);
+    childIssueIdsByParent.set(row.parentIssueId, existing);
+  }
+  const attachmentRows =
+    issueIds.length > 0
+      ? await db
+          .select({
+            id: issueAttachments.id,
+            issueId: issueAttachments.issueId,
+            projectId: issueAttachments.projectId,
+            fileName: issueAttachments.fileName,
+            mimeType: issueAttachments.mimeType,
+            fileSizeBytes: issueAttachments.fileSizeBytes,
+            relativePath: issueAttachments.relativePath
+          })
+          .from(issueAttachments)
+          .where(and(eq(issueAttachments.companyId, companyId), inArray(issueAttachments.issueId, issueIds)))
+      : [];
+  const attachmentsByIssue = new Map<
+    string,
+    Array<{
+      id: string;
+      fileName: string;
+      mimeType: string | null;
+      fileSizeBytes: number;
+      relativePath: string;
+      absolutePath: string;
+    }>
+  >();
+  for (const row of attachmentRows) {
+    const projectWorkspace = projectWorkspaceMap.get(row.projectId) ?? resolveProjectWorkspacePath(companyId, row.projectId);
+    const absolutePath = resolve(projectWorkspace, row.relativePath);
+    if (!isInsidePath(projectWorkspace, absolutePath)) {
+      continue;
+    }
+    const existing = attachmentsByIssue.get(row.issueId) ?? [];
+    existing.push({
+      id: row.id,
+      fileName: row.fileName,
+      mimeType: row.mimeType,
+      fileSizeBytes: row.fileSizeBytes,
+      relativePath: row.relativePath,
+      absolutePath
+    });
+    attachmentsByIssue.set(row.issueId, existing);
+  }
+  const goalRows = await db
+    .select({
+      id: goals.id,
+      level: goals.level,
+      title: goals.title,
+      status: goals.status,
+      projectId: goals.projectId
+    })
+    .from(goals)
+    .where(eq(goals.companyId, companyId));
+
+  const activeCompanyGoals = goalRows
+    .filter((goal) => goal.status === "active" && goal.level === "company")
+    .map((goal) => goal.title);
+  const activeProjectGoals = goalRows
+    .filter(
+      (goal) =>
+        goal.status === "active" && goal.level === "project" && goal.projectId && projectIds.includes(goal.projectId)
+    )
+    .map((goal) => goal.title);
+  const activeAgentGoals = goalRows
+    .filter((goal) => goal.status === "active" && goal.level === "agent")
+    .map((goal) => goal.title);
+  const isCommentOrderWake = input.wakeContext?.reason === "issue_comment_recipient";
+
+  return {
+    companyId,
+    agentId: input.agentId,
+    providerType: input.providerType,
+    heartbeatRunId: input.heartbeatRunId,
+    company: {
+      name: company?.name ?? "Unknown company",
+      mission: company?.mission ?? null
+    },
+    agent: {
+      name: input.agentName,
+      role: input.agentRole,
+      managerAgentId: input.managerAgentId
+    },
+    state: input.state,
+    memoryContext: input.memoryContext,
+    runtime: input.runtime,
+    wakeContext: input.wakeContext
+      ? {
+          reason: input.wakeContext.reason ?? null,
+          commentId: input.wakeContext.commentId ?? null,
+          commentBody: input.wakeContext.commentBody ?? null,
+          issueIds: input.wakeContext.issueIds ?? []
+        }
+      : undefined,
+    goalContext: {
+      companyGoals: activeCompanyGoals,
+      projectGoals: activeProjectGoals,
+      agentGoals: activeAgentGoals
+    },
+    workItems: input.workItems.map((item) => ({
+      issueId: item.id,
+      projectId: item.project_id,
+      parentIssueId: item.parent_issue_id,
+      childIssueIds: childIssueIdsByParent.get(item.id) ?? [],
+      projectName: projectNameById.get(item.project_id) ?? null,
+      title: item.title,
+      // Comment-order runs should treat linked issues as context-only, not as a full issue execution order.
+      body: isCommentOrderWake ? null : item.body,
+      status: item.status,
+      priority: item.priority,
+      labels: parseStringArray(item.labels_json),
+      tags: parseStringArray(item.tags_json),
+      attachments: isCommentOrderWake ? [] : (attachmentsByIssue.get(item.id) ?? [])
+    }))
+  };
+}
+
+function parseStringArray(value: string | null) {
+  if (!value) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    return Array.isArray(parsed) ? parsed.map((entry) => String(entry)) : [];
+  } catch {
+    return [];
+  }
+}
+
+function computeMissionAlignmentSignal(input: {
+  summary: string;
+  mission: string | null;
+  companyGoals: string[];
+  projectGoals: string[];
+}) {
+  const summaryTokens = new Set(tokenizeAlignmentText(input.summary));
+  const missionTokens = tokenizeAlignmentText(input.mission ?? "");
+  const goalTokens = tokenizeAlignmentText([...input.companyGoals, ...input.projectGoals].join(" "));
+  const matchedMissionTerms = missionTokens.filter((token) => summaryTokens.has(token));
+  const matchedGoalTerms = goalTokens.filter((token) => summaryTokens.has(token));
+  const missionScore = missionTokens.length > 0 ? matchedMissionTerms.length / missionTokens.length : 0;
+  const goalScore = goalTokens.length > 0 ? matchedGoalTerms.length / goalTokens.length : 0;
+  const score = Number(Math.min(1, missionScore * 0.55 + goalScore * 0.45).toFixed(3));
+  return {
+    score,
+    matchedMissionTerms,
+    matchedGoalTerms
+  };
+}
+
+function tokenizeAlignmentText(value: string) {
+  return Array.from(
+    new Set(
+      value
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length >= 3)
+    )
+  );
+}
+
+async function loadProjectIdsForRunBudgetCheck(
+  db: BopoDb,
+  companyId: string,
+  agentId: string,
+  wakeContext?: HeartbeatWakeContext
+) {
+  const projectIds = new Set<string>();
+  const isCommentOrderWake = wakeContext?.reason === "issue_comment_recipient";
+  if (!isCommentOrderWake) {
+    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"]),
+          eq(issues.isClaimed, false)
+        )
+      );
+    for (const row of assignedRows) {
+      projectIds.add(row.projectId);
+    }
+  }
+  const wakeIssueIds = Array.from(new Set((wakeContext?.issueIds ?? []).map((entry) => entry.trim()).filter(Boolean)));
+  if (wakeIssueIds.length > 0) {
+    const wakeRows = await db
+      .select({ projectId: issues.projectId })
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), inArray(issues.id, wakeIssueIds)));
+    for (const row of wakeRows) {
+      projectIds.add(row.projectId);
+    }
+  }
+  return Array.from(projectIds);
+}
+
+function buildProjectBudgetCostAllocations(
+  workItems: Array<{ issueId: string; projectId: string }>,
+  usdCost: number
+): Array<{ projectId: string; usdCost: number }> {
+  const effectiveCost = Math.max(0, usdCost);
+  if (effectiveCost <= 0 || workItems.length === 0) {
+    return [];
+  }
+  const issueCountByProject = new Map<string, number>();
+  for (const item of workItems) {
+    issueCountByProject.set(item.projectId, (issueCountByProject.get(item.projectId) ?? 0) + 1);
+  }
+  const totalIssues = Array.from(issueCountByProject.values()).reduce((sum, count) => sum + count, 0);
+  if (totalIssues <= 0) {
+    return [];
+  }
+  const projectIds = Array.from(issueCountByProject.keys());
+  let allocated = 0;
+  const allocations = projectIds.map((projectId, index) => {
+    if (index === projectIds.length - 1) {
+      return {
+        projectId,
+        usdCost: Number((effectiveCost - allocated).toFixed(6))
+      };
+    }
+    const count = issueCountByProject.get(projectId) ?? 0;
+    const share = Number(((effectiveCost * count) / totalIssues).toFixed(6));
+    allocated += share;
+    return {
+      projectId,
+      usdCost: share
+    };
+  });
+  return allocations.filter((entry) => entry.usdCost > 0);
+}
+
+async function ensureBudgetOverrideApprovalRequest(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    agentId: string;
+    utilizationPct: number;
+    usedBudgetUsd: number;
+    monthlyBudgetUsd: number;
+    runId: string;
+  }
+): Promise<string | null> {
+  const pendingOverrides = await db
+    .select({ id: approvalRequests.id, payloadJson: approvalRequests.payloadJson })
+    .from(approvalRequests)
+    .where(
+      and(
+        eq(approvalRequests.companyId, input.companyId),
+        eq(approvalRequests.action, "override_budget"),
+        eq(approvalRequests.status, "pending")
+      )
+    );
+  const alreadyPending = pendingOverrides.some((approval) => {
+    try {
+      const payload = JSON.parse(approval.payloadJson) as Record<string, unknown>;
+      return payload.agentId === input.agentId;
+    } catch {
+      return false;
+    }
+  });
+  if (alreadyPending) {
+    return null;
+  }
+  const recommendedAdditionalBudgetUsd = Math.max(1, Math.ceil(Math.max(input.monthlyBudgetUsd * 0.25, 1)));
+  const approvalId = await createApprovalRequest(db, {
+    companyId: input.companyId,
+    action: "override_budget",
+    payload: {
+      agentId: input.agentId,
+      reason: "Agent reached budget hard-stop and needs additional funds.",
+      currentMonthlyBudgetUsd: input.monthlyBudgetUsd,
+      usedBudgetUsd: input.usedBudgetUsd,
+      utilizationPct: input.utilizationPct,
+      additionalBudgetUsd: recommendedAdditionalBudgetUsd,
+      revisedMonthlyBudgetUsd: Number((input.monthlyBudgetUsd + recommendedAdditionalBudgetUsd).toFixed(4)),
+      triggerRunId: input.runId
+    }
+  });
+  await appendAuditEvent(db, {
+    companyId: input.companyId,
+    actorType: "system",
+    eventType: "budget.override_requested",
+    entityType: "approval",
+    entityId: approvalId,
+    correlationId: input.runId,
+    payload: {
+      agentId: input.agentId,
+      runId: input.runId,
+      currentMonthlyBudgetUsd: input.monthlyBudgetUsd,
+      usedBudgetUsd: input.usedBudgetUsd,
+      utilizationPct: input.utilizationPct,
+      additionalBudgetUsd: recommendedAdditionalBudgetUsd
+    }
+  });
+  return approvalId;
+}
+
+async function ensureProjectBudgetOverrideApprovalRequest(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    projectId: string;
+    utilizationPct: number;
+    usedBudgetUsd: number;
+    monthlyBudgetUsd: number;
+    runId: string;
+  }
+): Promise<string | null> {
+  const pendingOverrides = await db
+    .select({ id: approvalRequests.id, payloadJson: approvalRequests.payloadJson })
+    .from(approvalRequests)
+    .where(
+      and(
+        eq(approvalRequests.companyId, input.companyId),
+        eq(approvalRequests.action, "override_budget"),
+        eq(approvalRequests.status, "pending")
+      )
+    );
+  const alreadyPending = pendingOverrides.some((approval) => {
+    try {
+      const payload = JSON.parse(approval.payloadJson) as Record<string, unknown>;
+      return payload.projectId === input.projectId;
+    } catch {
+      return false;
+    }
+  });
+  if (alreadyPending) {
+    return null;
+  }
+  const recommendedAdditionalBudgetUsd = Math.max(1, Math.ceil(Math.max(input.monthlyBudgetUsd * 0.25, 1)));
+  const approvalId = await createApprovalRequest(db, {
+    companyId: input.companyId,
+    action: "override_budget",
+    payload: {
+      projectId: input.projectId,
+      reason: "Project reached budget hard-stop and needs additional funds.",
+      currentMonthlyBudgetUsd: input.monthlyBudgetUsd,
+      usedBudgetUsd: input.usedBudgetUsd,
+      utilizationPct: input.utilizationPct,
+      additionalBudgetUsd: recommendedAdditionalBudgetUsd,
+      revisedMonthlyBudgetUsd: Number((input.monthlyBudgetUsd + recommendedAdditionalBudgetUsd).toFixed(4)),
+      triggerRunId: input.runId
+    }
+  });
+  await appendAuditEvent(db, {
+    companyId: input.companyId,
+    actorType: "system",
+    eventType: "project_budget.override_requested",
+    entityType: "approval",
+    entityId: approvalId,
+    correlationId: input.runId,
+    payload: {
+      projectId: input.projectId,
+      runId: input.runId,
+      currentMonthlyBudgetUsd: input.monthlyBudgetUsd,
+      usedBudgetUsd: input.usedBudgetUsd,
+      utilizationPct: input.utilizationPct,
+      additionalBudgetUsd: recommendedAdditionalBudgetUsd
+    }
+  });
+  return approvalId;
+}
+
+function sanitizeAgentSummaryCommentBody(body: string) {
+  const sanitized = body.replace(AGENT_COMMENT_EMOJI_REGEX, "").trim();
+  return sanitized.length > 0 ? sanitized : "Run update.";
+}
+
+function extractNaturalRunUpdate(executionSummary: string) {
+  const normalized = executionSummary.trim();
+  const jsonSummary = extractSummaryFromJsonLikeText(normalized);
+  const source = jsonSummary ?? normalized;
+  const lines = source
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .filter((line) => !line.startsWith("{") && !line.startsWith("}"));
+  const compact = (lines.length > 0 ? lines.slice(0, 2).join(" ") : source)
+    .replace(/^run (failure )?summary\s*:\s*/i, "")
+    .replace(/^completed all assigned issue steps\s*:\s*/i, "")
+    .replace(/^issue status\s*:\s*/i, "")
+    .replace(/`+/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const bounded = compact.length > 260 ? `${compact.slice(0, 257).trimEnd()}...` : compact;
+  if (!bounded) {
+    return "Run update.";
+  }
+  return /[.!?]$/.test(bounded) ? bounded : `${bounded}.`;
+}
+
+function buildRunDigest(input: {
+  status: "completed" | "failed" | "skipped";
+  executionSummary: string;
+  outcome: ExecutionOutcome | null;
+  trace: unknown;
+  signals: RunDigestSignal[];
+}): RunDigest {
+  const summary = sanitizeAgentSummaryCommentBody(extractNaturalRunUpdate(input.executionSummary));
+  const successes: string[] = [];
+  const failures: string[] = [];
+  const blockers: string[] = [];
+  if (input.outcome) {
+    for (const action of input.outcome.actions) {
+      const detail = summarizeRunDigestPoint(action.detail);
+      if (!detail) {
+        continue;
+      }
+      if (action.status === "ok") {
+        successes.push(detail);
+      } else if (action.status === "error") {
+        failures.push(detail);
+      }
+    }
+    for (const blocker of input.outcome.blockers) {
+      const detail = summarizeRunDigestPoint(blocker.message);
+      if (detail) {
+        blockers.push(detail);
+      }
+    }
+  }
+  for (const signal of input.signals) {
+    if (signal.signalLevel !== "high" && signal.signalLevel !== "medium") {
+      continue;
+    }
+    const signalText = summarizeRunDigestPoint(signal.text ?? signal.payload ?? "");
+    if (!signalText) {
+      continue;
+    }
+    if (signal.kind === "tool_result" || signal.kind === "stderr") {
+      if (looksLikeRunFailureSignal(signalText)) {
+        failures.push(signalText);
+      } else if (signal.kind === "tool_result") {
+        successes.push(signalText);
+      }
+      continue;
+    }
+    if (signal.kind === "result" && !looksLikeRunFailureSignal(signalText)) {
+      successes.push(signalText);
+    }
+  }
+  if (input.status === "completed" && successes.length === 0) {
+    successes.push(summary);
+  }
+  if (input.status === "failed" && failures.length === 0) {
+    failures.push(summary);
+  }
+  if (input.status === "failed" && blockers.length === 0) {
+    const traceFailureType = summarizeRunDigestPoint(readTraceString(input.trace, "failureType") ?? "");
+    if (traceFailureType) {
+      blockers.push(`failure type: ${traceFailureType}`);
+    }
+  }
+  const uniqueSuccesses = dedupeRunDigestPoints(successes, 3);
+  const uniqueFailures = dedupeRunDigestPoints(failures, 3);
+  const uniqueBlockers = dedupeRunDigestPoints(blockers, 2);
+  const headline =
+    input.status === "completed"
+      ? `Run completed: ${summary}`
+      : input.status === "failed"
+        ? `Run failed: ${summary}`
+        : `Run skipped: ${summary}`;
+  const nextAction = resolveRunDigestNextAction({
+    status: input.status,
+    blockers: uniqueBlockers,
+    failures: uniqueFailures
+  });
+  return {
+    status: input.status,
+    headline,
+    summary,
+    successes: uniqueSuccesses,
+    failures: uniqueFailures,
+    blockers: uniqueBlockers,
+    nextAction,
+    evidence: {
+      transcriptSignalCount: input.signals.length,
+      outcomeActionCount: input.outcome?.actions.length ?? 0,
+      outcomeBlockerCount: input.outcome?.blockers.length ?? 0,
+      failureType: readTraceString(input.trace, "failureType")
+    }
+  };
+}
+
+function summarizeRunDigestPoint(value: string | null | undefined) {
+  if (!value) {
+    return "";
+  }
+  const normalized = sanitizeAgentSummaryCommentBody(extractNaturalRunUpdate(value));
+  if (!normalized || normalized.toLowerCase() === "run update.") {
+    return "";
+  }
+  const bounded = normalized.length > 180 ? `${normalized.slice(0, 177).trimEnd()}...` : normalized;
+  return bounded;
+}
+
+function dedupeRunDigestPoints(values: string[], limit: number) {
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const value of values) {
+    const key = value.toLowerCase().replace(/\s+/g, " ").trim();
+    if (!key || seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(value);
+    if (deduped.length >= limit) {
+      break;
+    }
+  }
+  return deduped;
+}
+
+function looksLikeRunFailureSignal(value: string) {
+  const normalized = value.toLowerCase();
+  return /(failed|error|exception|timed out|timeout|unauthorized|not supported|unsupported|no capacity|rate limit|429|500|blocked|unable to)/.test(
+    normalized
+  );
+}
+
+function resolveRunDigestNextAction(input: { status: "completed" | "failed" | "skipped"; blockers: string[]; failures: string[] }) {
+  if (input.status === "completed") {
+    return "Review outputs and move the issue to the next workflow state.";
+  }
+  const combined = [...input.blockers, ...input.failures].join(" ").toLowerCase();
+  if (combined.includes("auth") || combined.includes("unauthorized") || combined.includes("login")) {
+    return "Fix credentials/authentication, then rerun.";
+  }
+  if (combined.includes("model") && (combined.includes("not supported") || combined.includes("unavailable"))) {
+    return "Select a supported model and rerun.";
+  }
+  if (combined.includes("usage limit") || combined.includes("rate limit") || combined.includes("no capacity")) {
+    return "Retry after provider quota/capacity recovers.";
+  }
+  return "Fix listed failures/blockers and rerun.";
+}
+
+function resolveRunTerminalPresentation(input: {
+  internalStatus: "completed" | "failed" | "skipped";
+  executionSummary: string;
+  outcome: ExecutionOutcome | null;
+  trace: unknown;
+  errorType?: string | null;
+}) : RunTerminalPresentation {
+  if (isNoAssignedWorkOutcomeForReport(input.outcome)) {
+    return {
+      internalStatus: input.internalStatus,
+      publicStatus: "completed",
+      completionReason: "no_assigned_work"
+    };
+  }
+  if (input.internalStatus === "completed") {
+    return {
+      internalStatus: input.internalStatus,
+      publicStatus: "completed",
+      completionReason: "task_completed"
+    };
+  }
+  const completionReason = inferRunCompletionReason(input);
+  return {
+    internalStatus: input.internalStatus,
+    publicStatus: "failed",
+    completionReason
+  };
+}
+
+function inferRunCompletionReason(input: {
+  internalStatus: "completed" | "failed" | "skipped";
+  executionSummary: string;
+  outcome: ExecutionOutcome | null;
+  trace: unknown;
+  errorType?: string | null;
+}): RunCompletionReason {
+  const texts = [
+    input.executionSummary,
+    readTraceString(input.trace, "failureType") ?? "",
+    readTraceString(input.trace, "stderrPreview") ?? "",
+    input.errorType ?? "",
+    ...(input.outcome?.blockers ?? []).flatMap((blocker) => [blocker.code, blocker.message]),
+    ...(input.outcome?.actions ?? []).flatMap((action) => [action.type, action.detail ?? ""])
+  ];
+  const combined = texts.join("\n").toLowerCase();
+  if (
+    combined.includes("insufficient_quota") ||
+    combined.includes("billing_hard_limit_reached") ||
+    combined.includes("out of funds") ||
+    combined.includes("payment required")
+  ) {
+    return "provider_out_of_funds";
+  }
+  if (
+    combined.includes("usage limit") ||
+    combined.includes("rate limit") ||
+    combined.includes("429") ||
+    combined.includes("quota")
+  ) {
+    return combined.includes("quota") ? "provider_quota_exhausted" : "provider_rate_limited";
+  }
+  if (combined.includes("budget hard-stop")) {
+    return "budget_hard_stop";
+  }
+  if (combined.includes("already in progress") || combined.includes("skipped_overlap")) {
+    return "overlap_in_progress";
+  }
+  if (combined.includes("unauthorized") || combined.includes("auth") || combined.includes("api key")) {
+    return "auth_error";
+  }
+  if (combined.includes("contract") || combined.includes("missing_structured_output")) {
+    return "contract_invalid";
+  }
+  if (combined.includes("watchdog_timeout") || combined.includes("runtime_timeout") || combined.includes("timed out")) {
+    return "timeout";
+  }
+  if (combined.includes("cancelled")) {
+    return "cancelled";
+  }
+  if (combined.includes("enoent") || combined.includes("runtime_missing")) {
+    return "runtime_missing";
+  }
+  if (
+    combined.includes("provider unavailable") ||
+    combined.includes("no capacity") ||
+    combined.includes("unavailable") ||
+    combined.includes("http_error")
+  ) {
+    return "provider_unavailable";
+  }
+  if (input.outcome?.kind === "blocked") {
+    return "blocked";
+  }
+  return "runtime_error";
+}
+
+function isNoAssignedWorkOutcomeForReport(outcome: ExecutionOutcome | null) {
+  if (!outcome) {
+    return false;
+  }
+  if (outcome.kind !== "skipped") {
+    return false;
+  }
+  if (outcome.issueIdsTouched.length === 0) {
+    return true;
+  }
+  return outcome.actions.some((action) => action.type === "heartbeat.skip");
+}
+
+function buildRunCostSummary(input: {
+  tokenInput: number;
+  tokenOutput: number;
+  usdCost: number | null;
+  usdCostStatus: "exact" | "estimated" | "unknown";
+  pricingSource: string | null;
+  source: string | null;
+}): RunCostSummary {
+  return {
+    tokenInput: Math.max(0, input.tokenInput),
+    tokenOutput: Math.max(0, input.tokenOutput),
+    usdCost: input.usdCostStatus === "unknown" ? null : Math.max(0, input.usdCost ?? 0),
+    usdCostStatus: input.usdCostStatus,
+    pricingSource: input.pricingSource ?? null,
+    source: input.source ?? null
+  };
+}
+
+function buildRunArtifacts(input: {
+  outcome: ExecutionOutcome | null;
+  finalRunOutput?: AgentFinalRunOutput | null;
+  runtimeCwd?: string | null;
+  workspaceRootPath?: string | null;
+  companyId?: string;
+}): RunArtifact[] {
+  const sourceArtifacts =
+    input.finalRunOutput?.artifacts && input.finalRunOutput.artifacts.length > 0
+      ? input.finalRunOutput.artifacts
+      : input.outcome?.artifacts ?? [];
+  if (sourceArtifacts.length === 0) {
+    return [];
+  }
+  const runtimeCwd = input.runtimeCwd?.trim() ? input.runtimeCwd.trim() : null;
+  const workspaceRootPath = input.workspaceRootPath?.trim() ? input.workspaceRootPath.trim() : null;
+  const companyId = input.companyId?.trim() ? input.companyId.trim() : null;
+  return sourceArtifacts.map((artifact) => {
+    const originalPath = artifact.path.trim();
+    const artifactIsAbsolute = isAbsolute(originalPath);
+    const absolutePath = artifactIsAbsolute ? resolve(originalPath) : runtimeCwd ? resolve(runtimeCwd, originalPath) : null;
+    let relativePathValue: string | null = null;
+    if (absolutePath && workspaceRootPath && isInsidePath(workspaceRootPath, absolutePath)) {
+      relativePathValue = toNormalizedWorkspaceRelativePath(relative(workspaceRootPath, absolutePath));
+    } else if (!artifactIsAbsolute) {
+      relativePathValue = toNormalizedWorkspaceRelativePath(originalPath);
+    } else if (runtimeCwd) {
+      const candidate = toNormalizedWorkspaceRelativePath(relative(runtimeCwd, absolutePath ?? originalPath));
+      relativePathValue = candidate && !candidate.startsWith("../") ? candidate : null;
+    }
+    if (companyId) {
+      const normalizedRelative = normalizeAgentOperatingArtifactRelativePath(relativePathValue, companyId);
+      if (normalizedRelative) {
+        relativePathValue = normalizedRelative;
+      } else {
+        const normalizedOriginal = toNormalizedWorkspaceRelativePath(originalPath);
+        const normalizedFromOriginal = normalizeAgentOperatingArtifactRelativePath(normalizedOriginal, companyId);
+        if (normalizedFromOriginal) {
+          relativePathValue = normalizedFromOriginal;
+        }
+      }
+    }
+    const location = relativePathValue ?? absolutePath ?? originalPath;
+    return {
+      path: originalPath,
+      kind: artifact.kind,
+      label: describeArtifact(artifact.kind, location),
+      relativePath: relativePathValue,
+      absolutePath
+    };
+  });
+}
+
+function toNormalizedWorkspaceRelativePath(inputPath: string | null | undefined) {
+  const trimmed = inputPath?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const unixSeparated = trimmed.replace(/\\/g, "/");
+  const parts: string[] = [];
+  for (const part of unixSeparated.split("/")) {
+    if (!part || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      if (parts.length > 0 && parts[parts.length - 1] !== "..") {
+        parts.pop();
+      } else {
+        parts.push(part);
+      }
+      continue;
+    }
+    parts.push(part);
+  }
+  const normalized = parts.join("/");
+  return normalized || null;
+}
+
+function normalizeAgentOperatingArtifactRelativePath(pathValue: string | null, companyId: string) {
+  const normalized = toNormalizedWorkspaceRelativePath(pathValue);
+  if (!normalized) {
+    return null;
+  }
+  const workspaceScopedMatch = normalized.match(/(?:^|\/)(workspace\/[^/]+\/agents\/[^/]+\/operating(?:\/.*)?)$/);
+  if (workspaceScopedMatch) {
+    const scopedPath = toNormalizedWorkspaceRelativePath(workspaceScopedMatch[1]);
+    if (!scopedPath) {
+      return null;
+    }
+    const parsed = scopedPath.match(/^workspace\/([^/]+)\/agents\/([^/]+)\/operating(\/.*)?$/);
+    if (!parsed) {
+      return null;
+    }
+    const embeddedCompanyId = parsed[1]?.trim() || companyId;
+    const agentId = parsed[2];
+    const suffix = parsed[3] ?? "";
+    const effectiveCompanyId = embeddedCompanyId;
+    return `workspace/${effectiveCompanyId}/agents/${agentId}/operating${suffix}`;
+  }
+  const directMatch = normalized.match(/^agents\/([^/]+)\/operating(\/.*)?$/);
+  if (directMatch) {
+    const [, agentId, suffix = ""] = directMatch;
+    return `workspace/${companyId}/agents/${agentId}/operating${suffix}`;
+  }
+  const issueScopedMatch = normalized.match(
+    /^(?:[^/]+\/)?projects\/[^/]+\/issues\/[^/]+\/agents\/([^/]+)\/operating(\/.*)?$/
+  );
+  if (issueScopedMatch) {
+    const [, agentId, suffix = ""] = issueScopedMatch;
+    return `workspace/${companyId}/agents/${agentId}/operating${suffix}`;
+  }
+  return null;
+}
+
+function describeArtifact(kind: string, location: string) {
+  const normalizedKind = kind.toLowerCase();
+  if (normalizedKind.includes("folder") || normalizedKind.includes("directory") || normalizedKind === "website") {
+    return `Created ${normalizedKind.replace(/_/g, " ")} at ${location}`;
+  }
+  if (normalizedKind.includes("file")) {
+    return `Updated file ${location}`;
+  }
+  return `Produced ${normalizedKind.replace(/_/g, " ")} at ${location}`;
+}
+
+function buildRunCompletionReport(input: {
+  companyId?: string;
+  agentName: string;
+  providerType: HeartbeatProviderType;
+  issueIds: string[];
+  executionSummary: string;
+  outcome: ExecutionOutcome | null;
+  finalRunOutput?: AgentFinalRunOutput | null;
+  trace: unknown;
+  digest: RunDigest;
+  terminal: RunTerminalPresentation;
+  cost: RunCostSummary;
+  runtimeCwd?: string | null;
+  errorType?: string | null;
+  errorMessage?: string | null;
+}): RunCompletionReport {
+  const workspaceRootPath = input.companyId ? resolveCompanyWorkspaceRootPath(input.companyId) : null;
+  const artifacts = buildRunArtifacts({
+    outcome: input.outcome,
+    finalRunOutput: input.finalRunOutput,
+    runtimeCwd: input.runtimeCwd,
+    workspaceRootPath,
+    companyId: input.companyId
+  });
+  const fallbackSummary = sanitizeAgentSummaryCommentBody(extractNaturalRunUpdate(input.executionSummary));
+  const employeeComment =
+    input.finalRunOutput?.employee_comment?.trim() || buildLegacyEmployeeComment(fallbackSummary);
+  const results = input.finalRunOutput
+    ? input.finalRunOutput.results.filter((value): value is string => Boolean(value))
+    : input.terminal.publicStatus === "completed"
+      ? dedupeRunDigestPoints(
+          [
+            input.digest.successes[0],
+            artifacts[0]?.label,
+            input.terminal.completionReason === "no_assigned_work" ? "No assigned work was available for this run." : null
+          ].filter((value): value is string => Boolean(value)),
+          4
+        )
+      : [];
+  const errors =
+    input.finalRunOutput?.errors.filter((value): value is string => Boolean(value)) ??
+    dedupeRunDigestPoints([...input.digest.blockers, ...input.digest.failures].filter((value): value is string => Boolean(value)), 4);
+  const summary = firstMeaningfulReportLine(employeeComment) || results[0] || fallbackSummary;
+  const resultSummary =
+    results[0] ??
+    (input.terminal.publicStatus === "completed"
+      ? artifacts[0]?.label ??
+        (input.terminal.completionReason === "no_assigned_work" ? "No assigned work was available for this run." : summary)
+      : input.finalRunOutput
+        ? summary
+        : "No valid final run output was produced.");
+  const statusHeadline =
+    input.terminal.publicStatus === "completed"
+      ? `Completed: ${summary}`
+      : `Failed: ${summary}`;
+  const blockers = dedupeRunDigestPoints(errors, 4);
+  const artifactPaths = artifacts
+    .map((artifact) => artifact.relativePath ?? artifact.absolutePath ?? artifact.path)
+    .filter((value): value is string => Boolean(value));
+  const managerReport = {
+    agentName: input.agentName,
+    providerType: input.providerType,
+    whatWasDone: results[0] ?? (input.terminal.publicStatus === "completed" ? input.digest.successes[0] ?? summary : summary),
+    resultSummary,
+    artifactPaths,
+    blockers,
+    nextAction: input.digest.nextAction,
+    costLine: formatRunCostLine(input.cost)
+  };
+  const fallbackOutcome: ExecutionOutcome = input.outcome ?? {
+    kind:
+      input.terminal.completionReason === "no_assigned_work"
+        ? "skipped"
+        : input.terminal.publicStatus === "completed"
+          ? "completed"
+          : "failed",
+    issueIdsTouched: input.issueIds,
+    artifacts: artifacts.map((artifact) => ({ path: artifact.path, kind: artifact.kind })),
+    actions:
+      results.length > 0
+        ? results.slice(0, 4).map((result) => ({
+            type: input.terminal.publicStatus === "completed" ? "run.completed" : "run.failed",
+            status: input.terminal.publicStatus === "completed" ? "ok" : "error",
+            detail: result
+          }))
+        : [
+            {
+              type: input.terminal.publicStatus === "completed" ? "run.completed" : "run.failed",
+              status: input.terminal.publicStatus === "completed" ? "ok" : "error",
+              detail: managerReport.whatWasDone
+            }
+          ],
+    blockers: blockers.map((message) => ({
+      code: input.terminal.completionReason,
+      message,
+      retryable: input.terminal.publicStatus !== "completed"
+    })),
+    nextSuggestedState: input.terminal.publicStatus === "completed" ? "in_review" : "blocked"
+  };
+  return {
+    finalStatus: input.terminal.publicStatus,
+    completionReason: input.terminal.completionReason,
+    statusHeadline,
+    summary,
+    employeeComment,
+    results,
+    errors,
+    resultStatus: artifacts.length > 0 ? "reported" : "none_reported",
+    resultSummary,
+    issueIds: input.issueIds,
+    artifacts,
+    blockers,
+    nextAction: input.digest.nextAction,
+    cost: input.cost,
+    managerReport,
+    outcome: input.outcome ?? fallbackOutcome,
+    debug: {
+      persistedRunStatus: input.terminal.internalStatus,
+      failureType: readTraceString(input.trace, "failureType"),
+      errorType: input.errorType ?? null,
+      errorMessage: input.errorMessage ?? null
+    }
+  };
+}
+
+function firstMeaningfulReportLine(value: string) {
+  for (const rawLine of value.split(/\r?\n/)) {
+    const line = rawLine.replace(/^[#>*\-\s`]+/, "").trim();
+    if (line) {
+      return line;
+    }
+  }
+  return "";
+}
+
+function buildLegacyEmployeeComment(summary: string) {
+  return summary;
+}
+
+function formatRunCostLine(cost: RunCostSummary) {
+  const tokens = `${cost.tokenInput} input / ${cost.tokenOutput} output tokens`;
+  if (cost.usdCostStatus === "unknown" || cost.usdCost === null || cost.usdCost === undefined) {
+    return `${tokens}; dollar cost unknown`;
+  }
+  const qualifier = cost.usdCostStatus === "estimated" ? "estimated" : "exact";
+  return `${tokens}; ${qualifier} cost $${cost.usdCost.toFixed(6)}`;
+}
+
+function buildHumanRunUpdateCommentFromReport(
+  report: RunCompletionReport,
+  options: { runId: string; companyId: string }
+) {
+  const lines = [
+    report.employeeComment.trim(),
+    "",
+    `- Status: ${report.finalStatus}`,
+    `- Agent: ${report.managerReport.agentName}`,
+    `- Provider: ${report.managerReport.providerType}`,
+    ""
+  ];
+  if (report.results.length > 0) {
+    lines.push("### Results", "");
+    for (const result of report.results) {
+      lines.push(`- ${result}`);
+    }
+    lines.push("");
+  }
+  lines.push("### Result", "", `- What was done: ${report.managerReport.whatWasDone}`, `- Summary: ${report.managerReport.resultSummary}`);
+  if (report.artifacts.length > 0) {
+    for (const [artifactIndex, artifact] of report.artifacts.entries()) {
+      lines.push(`- Artifact: ${formatRunArtifactMarkdownLink(artifact, { ...options, artifactIndex })}`);
+    }
+  }
+  lines.push("");
+  lines.push("### Cost", "");
+  lines.push(`- Input tokens: \`${report.cost.tokenInput}\``);
+  lines.push(`- Output tokens: \`${report.cost.tokenOutput}\``);
+  lines.push(`- Dollar cost: ${formatRunCostForHumanReport(report.cost)}`);
+  if (report.errors.length > 0) {
+    lines.push("");
+    lines.push("### Errors", "");
+    for (const error of report.errors) {
+      lines.push(`- ${error}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function formatRunArtifactMarkdownLink(
+  artifact: RunArtifact,
+  options: { runId: string; companyId: string; artifactIndex: number }
+) {
+  const label = resolveRunArtifactDisplayPath(artifact);
+  const href = buildRunArtifactLinkHref(options);
+  if (!label) {
+    return "`artifact`";
+  }
+  if (!href) {
+    return `\`${label}\``;
+  }
+  return `[${label}](${href})`;
+}
+
+function resolveRunArtifactDisplayPath(artifact: RunArtifact) {
+  const relative = toNormalizedWorkspaceRelativePath(artifact.relativePath);
+  if (relative && !relative.startsWith("../")) {
+    return relative;
+  }
+  const pathValue = toNormalizedWorkspaceRelativePath(artifact.path);
+  if (pathValue && !pathValue.startsWith("../") && !isAbsolute(artifact.path)) {
+    return pathValue;
+  }
+  return null;
+}
+
+function buildRunArtifactLinkHref(options: { runId: string; companyId: string; artifactIndex: number }) {
+  const apiBaseUrl = resolveControlPlaneApiBaseUrl().replace(/\/+$/, "");
+  const runId = encodeURIComponent(options.runId);
+  const artifactIndex = encodeURIComponent(String(options.artifactIndex));
+  const companyId = encodeURIComponent(options.companyId);
+  return `${apiBaseUrl}/observability/heartbeats/${runId}/artifacts/${artifactIndex}/download?companyId=${companyId}`;
+}
+
+function formatRunCostForHumanReport(cost: RunCostSummary) {
+  if (cost.usdCostStatus === "unknown" || cost.usdCost === null || cost.usdCost === undefined) {
+    return "unknown";
+  }
+  const qualifier = cost.usdCostStatus === "estimated" ? "estimated " : "exact ";
+  return `${qualifier}\`$${cost.usdCost.toFixed(6)}\``;
+}
+
+function buildRunListMessageFromReport(report: RunCompletionReport) {
+  const resultParts =
+    report.finalStatus === "completed"
+      ? report.results.length > 0
+        ? report.results.slice(0, 2)
+        : [report.resultSummary]
+      : [];
+  const parts = [report.statusHeadline, ...resultParts];
+  if (report.artifacts.length > 0) {
+    parts.push(`Artifacts: ${report.managerReport.artifactPaths.join(", ")}`);
+  }
+  if (report.cost.usdCostStatus === "unknown") {
+    parts.push("Cost: unknown");
+  } else if (report.cost.usdCost !== null && report.cost.usdCost !== undefined) {
+    parts.push(`Cost: $${report.cost.usdCost.toFixed(6)}`);
+  }
+  const compact = parts.filter(Boolean).join(" | ");
+  return compact.length > 220 ? `${compact.slice(0, 217).trimEnd()}...` : compact;
+}
+
+function isMachineNoiseLine(text: string) {
+  const normalized = text.trim();
+  if (!normalized) {
+    return true;
+  }
+  if (normalized.length > 220) {
+    return true;
+  }
+  const patterns = [
+    /^command:\s*/i,
+    /^\s*[\[{].*[\]}]\s*$/,
+    /\/bin\/(bash|zsh|sh)/i,
+    /(^|\s)(\/Users\/|\/home\/|\/private\/var\/|[A-Za-z]:\\)/,
+    /\b(stderr|stdout|stack trace|exit code|payload_json|tokeninput|tokenoutput|usdcost)\b/i,
+    /(^|\s)at\s+\S+:\d+:\d+/,
+    /```/,
+    /\{[\s\S]*"(summary|tokenInput|tokenOutput|usdCost|trace|error)"[\s\S]*\}/i
+  ];
+  return patterns.some((pattern) => pattern.test(normalized));
+}
+
+function extractSummaryFromJsonLikeText(input: string) {
+  const fencedMatch = input.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fencedMatch?.[1]?.trim() ?? input.match(/\{[\s\S]*\}\s*$/)?.[0]?.trim();
+  if (!candidate) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(candidate) as Record<string, unknown>;
+    const summary = parsed.summary;
+    if (typeof summary === "string" && summary.trim().length > 0) {
+      return summary.trim();
     }
+  } catch {
+    // Fall through to regex extraction for loosely-formatted JSON.
   }
+  const summaryMatch = candidate.match(/"summary"\s*:\s*"([\s\S]*?)"/);
+  const summary = summaryMatch?.[1]
+    ?.replace(/\\"/g, "\"")
+    .replace(/\\n/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return summary && summary.length > 0 ? summary : null;
+}
 
-  const now = new Date();
-  const runs: string[] = [];
-  let skippedNotDue = 0;
-  let skippedStatus = 0;
-  let failedStarts = 0;
-  const sweepStartedAt = Date.now();
-  for (const agent of companyAgents) {
-    if (agent.status !== "idle" && agent.status !== "running") {
-      skippedStatus += 1;
-      continue;
-    }
-    if (!isHeartbeatDue(agent.heartbeatCron, latestRunByAgent.get(agent.id) ?? null, now)) {
-      skippedNotDue += 1;
-      continue;
-    }
-    try {
-      const runId = await runHeartbeatForAgent(db, companyId, agent.id, {
-        trigger: "scheduler",
-        requestId: options?.requestId,
-        realtimeHub: options?.realtimeHub
-      });
-      if (runId) {
-        runs.push(runId);
-      }
-    } catch {
-      failedStarts += 1;
-    }
+async function appendRunSummaryComments(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    issueIds: string[];
+    agentId: string;
+    runId: string;
+    report: RunCompletionReport;
   }
-  await appendAuditEvent(db, {
-    companyId,
-    actorType: "system",
-    eventType: "heartbeat.sweep.completed",
-    entityType: "company",
-    entityId: companyId,
-    correlationId: options?.requestId ?? null,
-    payload: {
-      runIds: runs,
-      startedCount: runs.length,
-      failedStarts,
-      skippedStatus,
-      skippedNotDue,
-      elapsedMs: Date.now() - sweepStartedAt,
-      requestId: options?.requestId ?? null
-    }
+) {
+  if (input.issueIds.length === 0) {
+    return;
+  }
+  const commentBody = buildHumanRunUpdateCommentFromReport(input.report, {
+    runId: input.runId,
+    companyId: input.companyId
   });
-  return runs;
+  for (const issueId of input.issueIds) {
+    const existingRunComments = await db
+      .select({ id: issueComments.id })
+      .from(issueComments)
+      .where(
+        and(
+          eq(issueComments.companyId, input.companyId),
+          eq(issueComments.issueId, issueId),
+          eq(issueComments.runId, input.runId),
+          eq(issueComments.authorType, "agent"),
+          eq(issueComments.authorId, input.agentId)
+        )
+      )
+      .orderBy(desc(issueComments.createdAt));
+    if (existingRunComments.length > 0) {
+      await db.delete(issueComments).where(
+        and(
+          eq(issueComments.companyId, input.companyId),
+          inArray(
+            issueComments.id,
+            existingRunComments.map((comment) => comment.id)
+          )
+        )
+      );
+    }
+    await addIssueComment(db, {
+      companyId: input.companyId,
+      issueId,
+      authorType: "agent",
+      authorId: input.agentId,
+      runId: input.runId,
+      body: commentBody
+    });
+  }
 }
 
-async function buildHeartbeatContext(
+async function appendProviderUsageLimitBoardComments(
   db: BopoDb,
-  companyId: string,
   input: {
+    companyId: string;
+    issueIds: string[];
     agentId: string;
-    agentName: string;
-    agentRole: string;
-    managerAgentId: string | null;
-    providerType: HeartbeatProviderType;
-    heartbeatRunId: string;
-    state: AgentState;
-    memoryContext?: HeartbeatContext["memoryContext"];
-    runtime?: { command?: string; args?: string[]; cwd?: string; timeoutMs?: number };
-    workItems: Array<{
-      id: string;
-      project_id: string;
-      title: string;
-      body: string | null;
-      status: string;
-      priority: string;
-      labels_json: string;
-      tags_json: string;
-    }>;
+    runId: string;
+    providerType: string;
+    message: string;
+    paused: boolean;
   }
-): Promise<HeartbeatContext> {
-  const [company] = await db
-    .select({ name: companies.name, mission: companies.mission })
-    .from(companies)
-    .where(eq(companies.id, companyId))
-    .limit(1);
-  const projectIds = Array.from(new Set(input.workItems.map((item) => item.project_id)));
-  const projectRows =
-    projectIds.length > 0
-      ? await db
-          .select({ id: projects.id, name: projects.name })
-          .from(projects)
-          .where(and(eq(projects.companyId, companyId), inArray(projects.id, projectIds)))
-      : [];
-  const projectNameById = new Map(projectRows.map((row) => [row.id, row.name]));
-  const projectWorkspaceContextMap = await getProjectWorkspaceContextMap(db, companyId, projectIds);
-  const projectWorkspaceMap = new Map(
-    Array.from(projectWorkspaceContextMap.entries()).map(([projectId, context]) => [projectId, context.cwd])
-  );
-  const issueIds = input.workItems.map((item) => item.id);
-  const attachmentRows =
-    issueIds.length > 0
-      ? await db
-          .select({
-            id: issueAttachments.id,
-            issueId: issueAttachments.issueId,
-            projectId: issueAttachments.projectId,
-            fileName: issueAttachments.fileName,
-            mimeType: issueAttachments.mimeType,
-            fileSizeBytes: issueAttachments.fileSizeBytes,
-            relativePath: issueAttachments.relativePath
-          })
-          .from(issueAttachments)
-          .where(and(eq(issueAttachments.companyId, companyId), inArray(issueAttachments.issueId, issueIds)))
-      : [];
-  const attachmentsByIssue = new Map<
-    string,
-    Array<{
-      id: string;
-      fileName: string;
-      mimeType: string | null;
-      fileSizeBytes: number;
-      relativePath: string;
-      absolutePath: string;
-    }>
-  >();
-  for (const row of attachmentRows) {
-    const projectWorkspace = projectWorkspaceMap.get(row.projectId) ?? resolveProjectWorkspacePath(companyId, row.projectId);
-    const absolutePath = resolve(projectWorkspace, row.relativePath);
-    if (!isInsidePath(projectWorkspace, absolutePath)) {
+) {
+  if (input.issueIds.length === 0) {
+    return;
+  }
+  const commentBody = buildProviderUsageLimitBoardCommentBody(input);
+  for (const issueId of input.issueIds) {
+    const [existingRunComment] = await db
+      .select({ id: issueComments.id })
+      .from(issueComments)
+      .where(
+        and(
+          eq(issueComments.companyId, input.companyId),
+          eq(issueComments.issueId, issueId),
+          eq(issueComments.runId, input.runId),
+          eq(issueComments.authorType, "system"),
+          eq(issueComments.authorId, input.agentId)
+        )
+      )
+      .limit(1);
+    if (existingRunComment) {
       continue;
     }
-    const existing = attachmentsByIssue.get(row.issueId) ?? [];
-    existing.push({
-      id: row.id,
-      fileName: row.fileName,
-      mimeType: row.mimeType,
-      fileSizeBytes: row.fileSizeBytes,
-      relativePath: row.relativePath,
-      absolutePath
+    await addIssueComment(db, {
+      companyId: input.companyId,
+      issueId,
+      authorType: "system",
+      authorId: input.agentId,
+      runId: input.runId,
+      recipients: [
+        {
+          recipientType: "board",
+          deliveryStatus: "pending"
+        }
+      ],
+      body: commentBody
     });
-    attachmentsByIssue.set(row.issueId, existing);
   }
-  const goalRows = await db
-    .select({
-      id: goals.id,
-      level: goals.level,
-      title: goals.title,
-      status: goals.status,
-      projectId: goals.projectId
-    })
-    .from(goals)
-    .where(eq(goals.companyId, companyId));
-
-  const activeCompanyGoals = goalRows
-    .filter((goal) => goal.status === "active" && goal.level === "company")
-    .map((goal) => goal.title);
-  const activeProjectGoals = goalRows
-    .filter(
-      (goal) =>
-        goal.status === "active" && goal.level === "project" && goal.projectId && projectIds.includes(goal.projectId)
-    )
-    .map((goal) => goal.title);
-  const activeAgentGoals = goalRows
-    .filter((goal) => goal.status === "active" && goal.level === "agent")
-    .map((goal) => goal.title);
+}
 
-  return {
-    companyId,
-    agentId: input.agentId,
-    providerType: input.providerType,
-    heartbeatRunId: input.heartbeatRunId,
-    company: {
-      name: company?.name ?? "Unknown company",
-      mission: company?.mission ?? null
-    },
-    agent: {
-      name: input.agentName,
-      role: input.agentRole,
-      managerAgentId: input.managerAgentId
-    },
-    state: input.state,
-    memoryContext: input.memoryContext,
-    runtime: input.runtime,
-    goalContext: {
-      companyGoals: activeCompanyGoals,
-      projectGoals: activeProjectGoals,
-      agentGoals: activeAgentGoals
-    },
-    workItems: input.workItems.map((item) => ({
-      issueId: item.id,
-      projectId: item.project_id,
-      projectName: projectNameById.get(item.project_id) ?? null,
-      title: item.title,
-      body: item.body,
-      status: item.status,
-      priority: item.priority,
-      labels: parseStringArray(item.labels_json),
-      tags: parseStringArray(item.tags_json),
-      attachments: attachmentsByIssue.get(item.id) ?? []
-    }))
-  };
+function buildProviderUsageLimitBoardCommentBody(input: {
+  providerType: string;
+  message: string;
+  paused: boolean;
+}) {
+  const providerLabel = input.providerType.replace(/[_-]+/g, " ").trim();
+  const normalizedProvider = providerLabel.charAt(0).toUpperCase() + providerLabel.slice(1);
+  const agentStateLine = input.paused ? "Agent paused." : "Agent already paused.";
+  return `${normalizedProvider} usage limit reached.\nRun failed due to provider limits.\n${agentStateLine}\nNext: resume after usage reset or billing/credential fix.`;
 }
 
-function parseStringArray(value: string | null) {
-  if (!value) {
-    return [];
+async function pauseAgentForProviderUsageLimit(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    agentId: string;
+    requestId: string;
+    runId: string;
+    providerType: string;
+    message: string;
   }
-  try {
-    const parsed = JSON.parse(value) as unknown;
-    return Array.isArray(parsed) ? parsed.map((entry) => String(entry)) : [];
-  } catch {
-    return [];
+) {
+  const [agentRow] = await db
+    .select({ status: agents.status })
+    .from(agents)
+    .where(and(eq(agents.companyId, input.companyId), eq(agents.id, input.agentId)))
+    .limit(1);
+  if (!agentRow || agentRow.status === "paused" || agentRow.status === "terminated") {
+    return { paused: false as const };
   }
+  await db
+    .update(agents)
+    .set({ status: "paused", updatedAt: new Date() })
+    .where(and(eq(agents.companyId, input.companyId), eq(agents.id, input.agentId)));
+  await appendAuditEvent(db, {
+    companyId: input.companyId,
+    actorType: "system",
+    eventType: "agent.paused_auto_provider_limit",
+    entityType: "agent",
+    entityId: input.agentId,
+    correlationId: input.requestId,
+    payload: {
+      runId: input.runId,
+      providerType: input.providerType,
+      reason: input.message
+    }
+  });
+  return { paused: true as const };
 }
 
 function parseAgentState(stateBlob: string | null) {
@@ -1859,6 +3876,7 @@ async function resolveRuntimeWorkspaceForWorkItems(
       continue;
     }
     let selectedWorkspaceCwd = normalizeCompanyWorkspacePath(companyId, baseWorkspaceCwd);
+    const projectIssue = workItems.find((item) => item.project_id === projectId);
     await mkdir(baseWorkspaceCwd, { recursive: true });
     try {
       if (hasText(projectContext.repoUrl)) {
@@ -1878,7 +3896,6 @@ async function resolveRuntimeWorkspaceForWorkItems(
         projectContext.policy?.strategy?.type === "git_worktree" &&
         resolveGitWorktreeIsolationEnabled()
       ) {
-        const projectIssue = workItems.find((item) => item.project_id === projectId);
         const worktree = await ensureIsolatedGitWorktree({
           companyId,
           repoCwd: selectedWorkspaceCwd,
@@ -1899,6 +3916,12 @@ async function resolveRuntimeWorkspaceForWorkItems(
       warnings.push(`Workspace bootstrap failed for project '${projectId}': ${message}`);
     }
 
+    if (projectIssue?.id) {
+      const issueScopedWorkspaceCwd = resolveProjectIssueWorkspaceCwd(companyId, selectedWorkspaceCwd, projectIssue.id);
+      await mkdir(issueScopedWorkspaceCwd, { recursive: true });
+      selectedWorkspaceCwd = issueScopedWorkspaceCwd;
+    }
+
     if (hasText(normalizedRuntimeCwd) && normalizedRuntimeCwd !== selectedWorkspaceCwd) {
       warnings.push(
         `Runtime cwd '${normalizedRuntimeCwd}' was overridden to project workspace '${selectedWorkspaceCwd}' for assigned work.`
@@ -1943,6 +3966,10 @@ async function resolveRuntimeWorkspaceForWorkItems(
   };
 }
 
+function resolveProjectIssueWorkspaceCwd(companyId: string, projectWorkspaceCwd: string, issueId: string) {
+  return normalizeCompanyWorkspacePath(companyId, join(projectWorkspaceCwd, "issues", issueId));
+}
+
 function resolveGitWorktreeIsolationEnabled() {
   const value = String(process.env.BOPO_ENABLE_GIT_WORKTREE_ISOLATION ?? "")
     .trim()
@@ -1958,6 +3985,39 @@ function resolveStaleRunThresholdMs() {
   return parsed;
 }
 
+function resolveHeartbeatSweepConcurrency(dueAgentsCount: number) {
+  const configured = Number(process.env.BOPO_HEARTBEAT_SWEEP_CONCURRENCY ?? "4");
+  const fallback = 4;
+  const normalized = Number.isFinite(configured) ? Math.floor(configured) : fallback;
+  if (normalized < 1) {
+    return 1;
+  }
+  // Prevent scheduler bursts from starving the API event loop.
+  const bounded = Math.min(normalized, 16);
+  return Math.min(bounded, Math.max(1, dueAgentsCount));
+}
+
+async function runWithConcurrency<T>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<void>
+) {
+  if (items.length === 0) {
+    return;
+  }
+  const workerCount = Math.max(1, Math.min(Math.floor(concurrency), items.length));
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (cursor < items.length) {
+        const index = cursor;
+        cursor += 1;
+        await worker(items[index] as T, index);
+      }
+    })
+  );
+}
+
 function resolveEffectiveStaleRunThresholdMs(input: {
   baseThresholdMs: number;
   runtimeTimeoutSec: number;
@@ -2245,6 +4305,7 @@ function buildHeartbeatRuntimeEnv(input: {
   agentId: string;
   heartbeatRunId: string;
   canHireAgents: boolean;
+  wakeContext?: HeartbeatWakeContext;
 }) {
   const apiBaseUrl = resolveControlPlaneApiBaseUrl();
   const actorPermissions = ["issues:write", ...(input.canHireAgents ? ["agents:write"] : [])].join(",");
@@ -2272,6 +4333,9 @@ function buildHeartbeatRuntimeEnv(input: {
     BOPODEV_REQUEST_HEADERS_JSON: actorHeaders,
     BOPODEV_REQUEST_APPROVAL_DEFAULT: "true",
     BOPODEV_CAN_HIRE_AGENTS: input.canHireAgents ? "true" : "false",
+    ...(input.wakeContext?.reason ? { BOPODEV_WAKE_REASON: input.wakeContext.reason } : {}),
+    ...(input.wakeContext?.commentId ? { BOPODEV_WAKE_COMMENT_ID: input.wakeContext.commentId } : {}),
+    ...(input.wakeContext?.issueIds?.length ? { BOPODEV_LINKED_ISSUE_IDS: input.wakeContext.issueIds.join(",") } : {}),
     ...(codexApiKey ? { OPENAI_API_KEY: codexApiKey } : {}),
     ...(claudeApiKey ? { ANTHROPIC_API_KEY: claudeApiKey } : {})
   } satisfies Record<string, string>;
@@ -2533,6 +4597,7 @@ function resolveRuntimeModelId(input: { runtimeModel?: string; stateBlob?: strin
 async function appendFinishedRunCostEntry(input: {
   db: BopoDb;
   companyId: string;
+  runId?: string | null;
   providerType: string;
   runtimeModelId: string | null;
   pricingProviderType?: string | null;
@@ -2559,25 +4624,22 @@ async function appendFinishedRunCostEntry(input: {
   const shouldPersist = input.status === "ok" || input.status === "failed";
   const runtimeUsdCost = Math.max(0, input.runtimeUsdCost ?? 0);
   const pricedUsdCost = Math.max(0, pricingDecision.usdCost);
-  const shouldUseRuntimeUsdCost = pricedUsdCost <= 0 && runtimeUsdCost > 0;
-  const baseUsdCost = shouldUseRuntimeUsdCost ? runtimeUsdCost : pricedUsdCost;
-  const effectiveUsdCost =
-    baseUsdCost > 0
-      ? baseUsdCost
-      : input.status === "failed" && input.failureType !== "spawn_error"
-        ? 0.000001
-        : 0;
+  const usdCostStatus: "exact" | "estimated" | "unknown" =
+    runtimeUsdCost > 0 ? "exact" : pricedUsdCost > 0 ? "estimated" : "unknown";
+  const effectiveUsdCost = usdCostStatus === "exact" ? runtimeUsdCost : usdCostStatus === "estimated" ? pricedUsdCost : 0;
   const effectivePricingSource = pricingDecision.pricingSource;
   const shouldPersistWithUsage =
-    shouldPersist && (input.tokenInput > 0 || input.tokenOutput > 0 || effectiveUsdCost > 0);
+    shouldPersist && (input.tokenInput > 0 || input.tokenOutput > 0 || usdCostStatus !== "unknown");
   if (shouldPersistWithUsage) {
     await appendCost(input.db, {
       companyId: input.companyId,
+      runId: input.runId ?? null,
       providerType: input.providerType,
       runtimeModelId: input.runtimeModelId,
       pricingProviderType: pricingDecision.pricingProviderType,
       pricingModelId: pricingDecision.pricingModelId,
       pricingSource: effectivePricingSource,
+      usdCostStatus,
       tokenInput: input.tokenInput,
       tokenOutput: input.tokenOutput,
       usdCost: effectiveUsdCost.toFixed(6),
@@ -2590,7 +4652,8 @@ async function appendFinishedRunCostEntry(input: {
   return {
     ...pricingDecision,
     pricingSource: effectivePricingSource,
-    usdCost: effectiveUsdCost
+    usdCost: effectiveUsdCost,
+    usdCostStatus
   };
 }