bopodev-api 0.1.25 → 0.1.26

package/src/services/heartbeat-service.ts

@@ -1,15 +1,20 @@
 import { mkdir } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { and, eq, inArray, sql } from "drizzle-orm";
+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 {
@@ -30,7 +35,12 @@ 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";
@@ -73,6 +83,39 @@ type HeartbeatWakeContext = {
 
 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,
   companyId: string,
@@ -334,18 +377,81 @@ export async function runHeartbeatForAgent(
   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",
-      message
+      finishedAt: new Date(),
+      message: runListMessage
     });
     publishHeartbeatRunStatus(options?.realtimeHub, {
       companyId,
       runId,
       status: "skipped",
-      message
+      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, {
@@ -386,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 }
+      }
     });
   }
 
@@ -518,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;
@@ -526,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;
@@ -553,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, {
@@ -943,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,
@@ -972,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,
@@ -983,6 +1235,7 @@ export async function runHeartbeatForAgent(
     const costDecision = await appendFinishedRunCostEntry({
       db,
       companyId,
+      runId,
       providerType: agent.providerType,
       runtimeModelId: effectivePricingModelId ?? runtimeModelId,
       pricingProviderType: effectivePricingProviderType,
@@ -994,7 +1247,7 @@ export async function runHeartbeatForAgent(
       issueId: primaryIssueId,
       projectId: primaryProjectId,
       agentId,
-      status: execution.status
+      status: persistedExecutionStatus
     });
     const executionUsdCost = costDecision.usdCost;
     await appendProjectBudgetUsage(db, {
@@ -1007,8 +1260,8 @@ export async function runHeartbeatForAgent(
       companyId,
       agentId,
       runId,
-      status: execution.status,
-      summary: execution.summary,
+      status: persistedExecutionStatus === "ok" ? "ok" : "failed",
+      summary: executionSummary,
       outcomeKind: executionOutcome?.kind ?? null,
       mission: context.company.mission ?? null,
       goalContext: {
@@ -1030,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,
@@ -1054,7 +1307,7 @@ export async function runHeartbeatForAgent(
       }
     }
     const missionAlignment = computeMissionAlignmentSignal({
-      summary: execution.summary,
+      summary: executionSummary,
       mission: context.company.mission ?? null,
       companyGoals: context.goalContext?.companyGoals ?? [],
       projectGoals: context.goalContext?.projectGoals ?? []
@@ -1079,7 +1332,7 @@ export async function runHeartbeatForAgent(
       executionUsdCost > 0 ||
       effectiveTokenInput > 0 ||
       effectiveTokenOutput > 0 ||
-      execution.status !== "skipped"
+      persistedExecutionStatus !== "skipped"
     ) {
       await db
         .update(agents)
@@ -1157,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
     });
@@ -1166,29 +1419,74 @@ 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,
-        status: execution.status === "failed" ? "failed" : "completed",
-        executionSummary: execution.summary
+        report: runReport
       });
     } catch (commentError) {
       await appendAuditEvent(db, {
@@ -1209,6 +1507,7 @@ export async function runHeartbeatForAgent(
     const fallbackMessages = normalizeTraceTranscript(executionTrace);
     const fallbackHighSignalCount = fallbackMessages.filter((message) => message.signalLevel === "high").length;
     const shouldAppendFallback =
+      !providerUsageLimitDisposition &&
       fallbackMessages.length > 0 &&
       (transcriptLiveCount === 0 ||
         transcriptLiveUsefulCount < 2 ||
@@ -1253,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,
@@ -1287,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
       },
@@ -1298,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",
@@ -1307,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,
@@ -1408,6 +1770,7 @@ export async function runHeartbeatForAgent(
     const failureCostDecision = await appendFinishedRunCostEntry({
       db,
       companyId,
+      runId,
       providerType: agent.providerType,
       runtimeModelId,
       pricingProviderType: agent.providerType,
@@ -1423,29 +1786,76 @@ export async function runHeartbeatForAgent(
       companyId,
       projectCostsUsd: buildProjectBudgetCostAllocations(executionWorkItemsForBudget, failureCostDecision.usdCost)
     });
+    const runDigest = buildRunDigest({
+      status: "failed",
+      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: executionSummary
+        message: runListMessage
       })
       .where(eq(heartbeatRuns.id, runId));
     publishHeartbeatRunStatus(options?.realtimeHub, {
       companyId,
       runId,
       status: "failed",
-      message: executionSummary,
+      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,
-        status: "failed",
-        executionSummary
+        report: runReport
       });
     } catch (commentError) {
       await appendAuditEvent(db, {
@@ -1472,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,
@@ -2290,16 +2705,6 @@ function sanitizeAgentSummaryCommentBody(body: string) {
   return sanitized.length > 0 ? sanitized : "Run update.";
 }
 
-function buildRunSummaryCommentBody(input: { status: "completed" | "failed"; executionSummary: string }) {
-  const summary = sanitizeAgentSummaryCommentBody(extractNaturalRunUpdate(input.executionSummary));
-  if (input.status === "failed") {
-    return summary.toLowerCase().startsWith("couldn't")
-      ? summary
-      : `Couldn't complete this run: ${summary.charAt(0).toLowerCase()}${summary.slice(1)}`;
-  }
-  return summary;
-}
-
 function extractNaturalRunUpdate(executionSummary: string) {
   const normalized = executionSummary.trim();
   const jsonSummary = extractSummaryFromJsonLikeText(normalized);
@@ -2323,6 +2728,676 @@ function extractNaturalRunUpdate(executionSummary: string) {
   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();
@@ -2354,19 +3429,18 @@ async function appendRunSummaryComments(
     issueIds: string[];
     agentId: string;
     runId: string;
-    status: "completed" | "failed";
-    executionSummary: string;
+    report: RunCompletionReport;
   }
 ) {
   if (input.issueIds.length === 0) {
     return;
   }
-  const commentBody = buildRunSummaryCommentBody({
-    status: input.status,
-    executionSummary: input.executionSummary
+  const commentBody = buildHumanRunUpdateCommentFromReport(input.report, {
+    runId: input.runId,
+    companyId: input.companyId
   });
   for (const issueId of input.issueIds) {
-    const [existingRunComment] = await db
+    const existingRunComments = await db
       .select({ id: issueComments.id })
       .from(issueComments)
       .where(
@@ -2378,6 +3452,58 @@ async function appendRunSummaryComments(
           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 appendProviderUsageLimitBoardComments(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    issueIds: string[];
+    agentId: string;
+    runId: string;
+    providerType: string;
+    message: string;
+    paused: boolean;
+  }
+) {
+  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;
@@ -2385,14 +3511,70 @@ async function appendRunSummaryComments(
     await addIssueComment(db, {
       companyId: input.companyId,
       issueId,
-      authorType: "agent",
+      authorType: "system",
       authorId: input.agentId,
       runId: input.runId,
+      recipients: [
+        {
+          recipientType: "board",
+          deliveryStatus: "pending"
+        }
+      ],
       body: commentBody
     });
   }
 }
 
+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.`;
+}
+
+async function pauseAgentForProviderUsageLimit(
+  db: BopoDb,
+  input: {
+    companyId: string;
+    agentId: string;
+    requestId: string;
+    runId: string;
+    providerType: string;
+    message: string;
+  }
+) {
+  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) {
   if (!stateBlob) {
     return { state: {} as AgentState, parseError: null };
@@ -2735,10 +3917,7 @@ async function resolveRuntimeWorkspaceForWorkItems(
     }
 
     if (projectIssue?.id) {
-      const issueScopedWorkspaceCwd = normalizeCompanyWorkspacePath(
-        companyId,
-        join(selectedWorkspaceCwd, "issues", projectIssue.id)
-      );
+      const issueScopedWorkspaceCwd = resolveProjectIssueWorkspaceCwd(companyId, selectedWorkspaceCwd, projectIssue.id);
       await mkdir(issueScopedWorkspaceCwd, { recursive: true });
       selectedWorkspaceCwd = issueScopedWorkspaceCwd;
     }
@@ -2787,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()
@@ -3414,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;
@@ -3440,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),
@@ -3471,7 +4652,8 @@ async function appendFinishedRunCostEntry(input: {
   return {
     ...pricingDecision,
     pricingSource: effectivePricingSource,
-    usdCost: effectiveUsdCost
+    usdCost: effectiveUsdCost,
+    usdCostStatus
   };
 }