bopodev-api 0.1.10 → 0.1.11

package/src/services/heartbeat-service.ts

@@ -3,6 +3,13 @@ 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 {
+  ControlPlaneHeadersJsonSchema,
+  ControlPlaneRequestHeadersSchema,
+  ControlPlaneRuntimeEnvSchema,
+  ExecutionOutcomeSchema,
+  type ExecutionOutcome
+} from "bopodev-contracts";
 import type { BopoDb } from "bopodev-db";
 import { agents, appendActivity, companies, goals, heartbeatRuns, issues, projects } from "bopodev-db";
 import { appendAuditEvent, appendCost } from "bopodev-db";
@@ -12,6 +19,20 @@ import type { RealtimeHub } from "../realtime/hub";
 import { publishOfficeOccupantForAgent } from "../realtime/office-space";
 import { checkAgentBudget } from "./budget-service";
 
+type HeartbeatRunTrigger = "manual" | "scheduler";
+type HeartbeatRunMode = "default" | "resume" | "redo";
+
+type ActiveHeartbeatRun = {
+  companyId: string;
+  agentId: string;
+  abortController: AbortController;
+  cancelReason?: string | null;
+  cancelRequestedAt?: string | null;
+  cancelRequestedBy?: string | null;
+};
+
+const activeHeartbeatRuns = new Map<string, ActiveHeartbeatRun>();
+
 export async function claimIssuesForAgent(
   db: BopoDb,
   companyId: string,
@@ -62,12 +83,95 @@ export async function releaseClaimedIssues(db: BopoDb, companyId: string, issueI
     .where(and(eq(issues.companyId, companyId), inArray(issues.id, issueIds)));
 }
 
+export async function stopHeartbeatRun(
+  db: BopoDb,
+  companyId: string,
+  runId: string,
+  options?: { requestId?: string; actorId?: string; trigger?: HeartbeatRunTrigger }
+) {
+  const runTrigger = options?.trigger ?? "manual";
+  const [run] = await db
+    .select({
+      id: heartbeatRuns.id,
+      status: heartbeatRuns.status,
+      agentId: heartbeatRuns.agentId
+    })
+    .from(heartbeatRuns)
+    .where(and(eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.id, runId)))
+    .limit(1);
+  if (!run) {
+    return { ok: false as const, reason: "not_found" as const };
+  }
+  if (run.status !== "started") {
+    return { ok: false as const, reason: "invalid_status" as const, status: run.status };
+  }
+  const active = activeHeartbeatRuns.get(runId);
+  const cancelReason = "cancelled by stop request";
+  const cancelRequestedAt = new Date().toISOString();
+  if (active) {
+    active.cancelReason = cancelReason;
+    active.cancelRequestedAt = cancelRequestedAt;
+    active.cancelRequestedBy = options?.actorId ?? null;
+    active.abortController.abort(cancelReason);
+  } else {
+    await db
+      .update(heartbeatRuns)
+      .set({
+        status: "failed",
+        finishedAt: new Date(),
+        message: "Heartbeat cancelled by stop request."
+      })
+      .where(and(eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.id, runId)));
+  }
+  await appendAuditEvent(db, {
+    companyId,
+    actorType: "system",
+    eventType: "heartbeat.cancel_requested",
+    entityType: "heartbeat_run",
+    entityId: runId,
+    correlationId: options?.requestId ?? runId,
+    payload: {
+      agentId: run.agentId,
+      trigger: runTrigger,
+      requestId: options?.requestId ?? null,
+      actorId: options?.actorId ?? null,
+      inMemoryAbortRegistered: Boolean(active)
+    }
+  });
+  if (!active) {
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.cancelled",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: {
+        agentId: run.agentId,
+        reason: cancelReason,
+        trigger: runTrigger,
+        requestId: options?.requestId ?? null,
+        actorId: options?.actorId ?? null
+      }
+    });
+  }
+  return { ok: true as const, runId, agentId: run.agentId, status: run.status };
+}
+
 export async function runHeartbeatForAgent(
   db: BopoDb,
   companyId: string,
   agentId: string,
-  options?: { requestId?: string; trigger?: "manual" | "scheduler"; realtimeHub?: RealtimeHub }
+  options?: {
+    requestId?: string;
+    trigger?: HeartbeatRunTrigger;
+    realtimeHub?: RealtimeHub;
+    mode?: HeartbeatRunMode;
+    sourceRunId?: string;
+  }
 ) {
+  const runMode = options?.mode ?? "default";
+  const runTrigger = options?.trigger ?? "manual";
   const [agent] = await db
     .select()
     .from(agents)
@@ -78,6 +182,7 @@ export async function runHeartbeatForAgent(
     return null;
   }
 
+  const persistedRuntime = parseRuntimeConfigFromAgentRow(agent as unknown as Record<string, unknown>);
   const startedRuns = await db
     .select({ id: heartbeatRuns.id, startedAt: heartbeatRuns.startedAt })
     .from(heartbeatRuns)
@@ -89,17 +194,22 @@ export async function runHeartbeatForAgent(
       )
     );
   const staleRunThresholdMs = resolveStaleRunThresholdMs();
+  const effectiveStaleRunThresholdMs = resolveEffectiveStaleRunThresholdMs({
+    baseThresholdMs: staleRunThresholdMs,
+    runtimeTimeoutSec: persistedRuntime.runtimeTimeoutSec,
+    interruptGraceSec: persistedRuntime.interruptGraceSec
+  });
   const nowTs = Date.now();
   const staleRuns = startedRuns.filter((run) => {
     const startedAt = run.startedAt.getTime();
-    return nowTs - startedAt >= staleRunThresholdMs;
+    return nowTs - startedAt >= effectiveStaleRunThresholdMs;
   });
 
   if (staleRuns.length > 0) {
     await recoverStaleHeartbeatRuns(db, companyId, agentId, staleRuns, {
       requestId: options?.requestId,
-      trigger: options?.trigger ?? "manual",
-      staleRunThresholdMs
+      trigger: runTrigger,
+      staleRunThresholdMs: effectiveStaleRunThresholdMs
     });
   }
 
@@ -129,7 +239,7 @@ export async function runHeartbeatForAgent(
         entityType: "heartbeat_run",
         entityId: skippedRunId,
         correlationId: options?.requestId ?? skippedRunId,
-        payload: { agentId, requestId: options?.requestId, trigger: options?.trigger ?? "manual" }
+        payload: { agentId, requestId: options?.requestId, trigger: runTrigger }
       });
       return skippedRunId;
     }
@@ -154,7 +264,9 @@ export async function runHeartbeatForAgent(
       payload: {
         agentId,
         requestId: options?.requestId ?? null,
-        trigger: options?.trigger ?? "manual"
+        trigger: runTrigger,
+        mode: runMode,
+        sourceRunId: options?.sourceRunId ?? null
       }
     });
   }
@@ -205,17 +317,21 @@ export async function runHeartbeatForAgent(
   } = {};
   let executionSummary = "";
   let executionTrace: unknown = null;
+  let executionOutcome: ExecutionOutcome | null = null;
   let stateParseError: string | null = null;
+  let runtimeLaunchSummary: ReturnType<typeof summarizeRuntimeLaunch> | null = null;
 
   try {
     const workItems = await claimIssuesForAgent(db, companyId, agentId, runId);
     issueIds = workItems.map((item) => item.id);
     await publishOfficeOccupantForAgent(db, options?.realtimeHub, companyId, agentId);
-    const adapter = resolveAdapter(agent.providerType as "claude_code" | "codex" | "http" | "shell");
+    const adapter = resolveAdapter(agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell");
     const parsedState = parseAgentState(agent.stateBlob);
     state = parsedState.state;
     stateParseError = parsedState.parseError;
-    const persistedRuntime = parseRuntimeConfigFromAgentRow(agent as unknown as Record<string, unknown>);
+    if (runMode === "redo") {
+      state = clearResumeState(state);
+    }
     const heartbeatRuntimeEnv = buildHeartbeatRuntimeEnv({
       companyId,
       agentId: agent.id,
@@ -255,7 +371,7 @@ export async function runHeartbeatForAgent(
       agentName: agent.name,
       agentRole: agent.role,
       managerAgentId: agent.managerAgentId,
-      providerType: agent.providerType as "claude_code" | "codex" | "http" | "shell",
+      providerType: agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
       heartbeatRunId: runId,
       state,
       runtime: workspaceResolution.runtime,
@@ -307,21 +423,25 @@ export async function runHeartbeatForAgent(
         payload: {
           agentId,
           providerType: agent.providerType,
-          missingKeys: controlPlaneEnvValidation.missingKeys
+          validationErrorCode: controlPlaneEnvValidation.validationErrorCode,
+          invalidFieldPaths: controlPlaneEnvValidation.invalidFieldPaths
         }
       });
       throw new Error(
-        `Control-plane runtime env is incomplete. Missing keys: ${controlPlaneEnvValidation.missingKeys.join(", ")}`
+        `Control-plane runtime env is invalid. Invalid fields: ${controlPlaneEnvValidation.invalidFieldPaths.join(", ")}`
       );
     }
 
     if (
       resolveControlPlanePreflightEnabled() &&
-      shouldRequireControlPlanePreflight(agent.providerType as "claude_code" | "codex" | "http" | "shell", workItems.length)
+      shouldRequireControlPlanePreflight(
+        agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+        workItems.length
+      )
     ) {
       const preflight = await runControlPlaneConnectivityPreflight({
-        apiBaseUrl: workspaceResolution.runtime.env?.BOPOHQ_API_BASE_URL ?? "",
-        requestHeadersJson: workspaceResolution.runtime.env?.BOPOHQ_REQUEST_HEADERS_JSON ?? "",
+        apiBaseUrl: resolveControlPlaneEnv(workspaceResolution.runtime.env ?? {}, "API_BASE_URL"),
+        runtimeEnv: workspaceResolution.runtime.env ?? {},
         timeoutMs: resolveControlPlanePreflightTimeoutMs()
       });
       await appendAuditEvent(db, {
@@ -342,6 +462,10 @@ export async function runHeartbeatForAgent(
       }
     }
 
+    runtimeLaunchSummary = summarizeRuntimeLaunch(
+      agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+      workspaceResolution.runtime
+    );
     await appendAuditEvent(db, {
       companyId,
       actorType: "system",
@@ -351,20 +475,56 @@ export async function runHeartbeatForAgent(
       correlationId: options?.requestId ?? runId,
       payload: {
         agentId,
-        runtime: summarizeRuntimeLaunch(
-          agent.providerType as "claude_code" | "codex" | "http" | "shell",
-          workspaceResolution.runtime
-        ),
+        runtime: runtimeLaunchSummary,
         diagnostics: {
           requestId: options?.requestId ?? null,
-          trigger: options?.trigger ?? "manual"
+          trigger: runTrigger,
+          mode: runMode,
+          sourceRunId: options?.sourceRunId ?? null
         }
       }
     });
+    if (runMode === "resume" || runMode === "redo") {
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: runMode === "resume" ? "heartbeat.resumed" : "heartbeat.redo_started",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          sourceRunId: options?.sourceRunId ?? null,
+          requestId: options?.requestId ?? null,
+          trigger: runTrigger
+        }
+      });
+    }
+
+    const activeRunAbort = new AbortController();
+    registerActiveHeartbeatRun(runId, {
+      companyId,
+      agentId,
+      abortController: activeRunAbort
+    });
 
-    const execution = await adapter.execute(context);
+    const execution = await executeAdapterWithWatchdog({
+      execute: (abortSignal) =>
+        adapter.execute({
+          ...context,
+          runtime: {
+            ...(context.runtime ?? {}),
+            abortSignal
+          }
+        }),
+      providerType: agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+      runtime: workspaceResolution.runtime,
+      externalAbortSignal: activeRunAbort.signal
+    });
     executionSummary = execution.summary;
     executionTrace = execution.trace ?? null;
+    const parsedOutcome = ExecutionOutcomeSchema.safeParse(execution.outcome);
+    executionOutcome = parsedOutcome.success ? parsedOutcome.data : null;
 
     if (execution.tokenInput > 0 || execution.tokenOutput > 0 || execution.usdCost > 0) {
       await appendCost(db, {
@@ -402,7 +562,8 @@ export async function runHeartbeatForAgent(
       tokenInput: execution.tokenInput,
       tokenOutput: execution.tokenOutput,
       usdCost: execution.usdCost,
-      trace: executionTrace
+      trace: executionTrace,
+      outcome: executionOutcome
     });
 
     if (issueIds.length > 0 && execution.status === "ok" && shouldAdvanceIssuesToReview) {
@@ -442,6 +603,7 @@ export async function runHeartbeatForAgent(
           issueIds,
           reason: "insufficient_real_execution_evidence",
           summary: execution.summary,
+          outcome: executionOutcome,
           usage: {
             tokenInput: execution.tokenInput,
             tokenOutput: execution.tokenOutput,
@@ -470,6 +632,8 @@ export async function runHeartbeatForAgent(
       payload: {
         agentId,
         result: execution.summary,
+        message: execution.summary,
+        outcome: executionOutcome,
         issueIds,
         usage: {
           tokenInput: execution.tokenInput,
@@ -481,13 +645,41 @@ export async function runHeartbeatForAgent(
         diagnostics: {
           stateParseError,
           requestId: options?.requestId,
-          trigger: options?.trigger ?? "manual"
+          trigger: runTrigger
         }
       }
     });
   } catch (error) {
     const classified = classifyHeartbeatError(error);
-    executionSummary = `Heartbeat failed (${classified.type}): ${classified.message}`;
+    executionSummary =
+      classified.type === "cancelled"
+        ? "Heartbeat cancelled by stop request."
+        : `Heartbeat failed (${classified.type}): ${classified.message}`;
+    if (!executionTrace && classified.type === "cancelled") {
+      executionTrace = {
+        command: runtimeLaunchSummary?.command ?? null,
+        args: runtimeLaunchSummary?.args ?? [],
+        cwd: runtimeLaunchSummary?.cwd ?? null,
+        failureType: "cancelled",
+        timedOut: false,
+        timeoutSource: null
+      };
+    } else if (!executionTrace && classified.type === "timeout") {
+      executionTrace = {
+        command: runtimeLaunchSummary?.command ?? null,
+        args: runtimeLaunchSummary?.args ?? [],
+        cwd: runtimeLaunchSummary?.cwd ?? null,
+        failureType: classified.timeoutSource === "watchdog" ? "watchdog_timeout" : "runtime_timeout",
+        timedOut: true,
+        timeoutSource: classified.timeoutSource ?? "watchdog"
+      };
+    } else if (!executionTrace && runtimeLaunchSummary) {
+      executionTrace = {
+        command: runtimeLaunchSummary.command ?? null,
+        args: runtimeLaunchSummary.args ?? [],
+        cwd: runtimeLaunchSummary.cwd ?? null
+      };
+    }
     await db
       .update(heartbeatRuns)
       .set({
@@ -506,8 +698,11 @@ export async function runHeartbeatForAgent(
       payload: {
         agentId,
         issueIds,
+        result: executionSummary,
+        message: executionSummary,
         errorType: classified.type,
         errorMessage: classified.message,
+        outcome: executionOutcome,
         usage: {
           source: readTraceString(executionTrace, "usageSource") ?? "unknown"
         },
@@ -515,11 +710,28 @@ export async function runHeartbeatForAgent(
         diagnostics: {
           stateParseError,
           requestId: options?.requestId,
-          trigger: options?.trigger ?? "manual"
+          trigger: runTrigger
         }
       }
     });
+    if (classified.type === "cancelled") {
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.cancelled",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          requestId: options?.requestId ?? null,
+          trigger: runTrigger,
+          result: executionSummary
+        }
+      });
+    }
   } finally {
+    unregisterActiveHeartbeatRun(runId);
     try {
       await releaseClaimedIssues(db, companyId, issueIds);
     } catch (releaseError) {
@@ -687,7 +899,7 @@ async function buildHeartbeatContext(
     agentName: string;
     agentRole: string;
     managerAgentId: string | null;
-    providerType: "claude_code" | "codex" | "http" | "shell";
+    providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell";
     heartbeatRunId: string;
     state: AgentState;
     runtime?: { command?: string; args?: string[]; cwd?: string; timeoutMs?: number };
@@ -825,13 +1037,20 @@ function parseAgentState(stateBlob: string | null) {
 
 function classifyHeartbeatError(error: unknown) {
   const message = String(error);
+  const normalized = message.toLowerCase();
+  if (error instanceof AdapterExecutionCancelledError || normalized.includes("adapter execution cancelled")) {
+    return { type: "cancelled" as const, timeoutSource: null, message };
+  }
+  if (error instanceof AdapterExecutionWatchdogTimeoutError || normalized.includes("adapter execution timed out")) {
+    return { type: "timeout" as const, timeoutSource: "watchdog" as const, message };
+  }
   if (message.includes("ENOENT")) {
-    return { type: "runtime_missing", message };
+    return { type: "runtime_missing" as const, timeoutSource: null, message };
   }
-  if (message.includes("timeout")) {
-    return { type: "timeout", message };
+  if (normalized.includes("timeout") || normalized.includes("timed out")) {
+    return { type: "timeout" as const, timeoutSource: "runtime" as const, message };
   }
-  return { type: "unknown", message };
+  return { type: "unknown" as const, timeoutSource: null, message };
 }
 
 function shouldPromoteIssuesToReview(input: {
@@ -840,7 +1059,23 @@ function shouldPromoteIssuesToReview(input: {
   tokenOutput: number;
   usdCost: number;
   trace: unknown;
+  outcome: ExecutionOutcome | null;
 }) {
+  if (input.outcome) {
+    if (isBootstrapDemoSummary(input.summary)) {
+      return false;
+    }
+    if (input.outcome.kind !== "completed") {
+      return false;
+    }
+    if (input.outcome.blockers.length > 0) {
+      return false;
+    }
+    if (input.outcome.nextSuggestedState === "blocked") {
+      return false;
+    }
+    return true;
+  }
   return !isBootstrapDemoSummary(input.summary) && hasRealExecutionEvidence(input);
 }
 
@@ -973,6 +1208,177 @@ function resolveStaleRunThresholdMs() {
   return parsed;
 }
 
+function resolveEffectiveStaleRunThresholdMs(input: {
+  baseThresholdMs: number;
+  runtimeTimeoutSec: number;
+  interruptGraceSec: number;
+}) {
+  if (!Number.isFinite(input.runtimeTimeoutSec) || input.runtimeTimeoutSec <= 0) {
+    return input.baseThresholdMs;
+  }
+  const timeoutMs = Math.floor(input.runtimeTimeoutSec * 1000);
+  const graceMs = Math.max(5_000, Math.floor(Math.max(0, input.interruptGraceSec) * 1000));
+  const jitterBufferMs = 30_000;
+  const derivedThresholdMs = timeoutMs + graceMs + jitterBufferMs;
+  const minimumThresholdMs = 30_000;
+  return Math.max(minimumThresholdMs, Math.min(input.baseThresholdMs, derivedThresholdMs));
+}
+
+async function executeAdapterWithWatchdog<T>(input: {
+  execute: (abortSignal: AbortSignal) => Promise<T>;
+  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell";
+  externalAbortSignal?: AbortSignal;
+  runtime:
+    | {
+        timeoutMs?: number;
+        interruptGraceSec?: number;
+      }
+    | undefined;
+}) {
+  const timeoutMs = resolveAdapterWatchdogTimeoutMs(input.providerType, input.runtime);
+  if (timeoutMs <= 0) {
+    return input.execute(input.externalAbortSignal ?? new AbortController().signal);
+  }
+  const executionAbort = new AbortController();
+  let timer: NodeJS.Timeout | null = null;
+  let externalAbortListener: (() => void) | null = null;
+  try {
+    if (input.externalAbortSignal) {
+      externalAbortListener = () => {
+        if (!executionAbort.signal.aborted) {
+          executionAbort.abort("external");
+        }
+      };
+      if (input.externalAbortSignal.aborted) {
+        externalAbortListener();
+      } else {
+        input.externalAbortSignal.addEventListener("abort", externalAbortListener, { once: true });
+      }
+    }
+    const executionPromise = input.execute(executionAbort.signal);
+    // If watchdog timeout wins race, suppress late adapter rejections after abort.
+    void executionPromise.catch(() => undefined);
+    const cancellationPromise = new Promise<T>((_, reject) => {
+      if (!input.externalAbortSignal) {
+        return;
+      }
+      if (input.externalAbortSignal.aborted) {
+        reject(new AdapterExecutionCancelledError("adapter execution cancelled by external stop request"));
+        return;
+      }
+      input.externalAbortSignal.addEventListener(
+        "abort",
+        () => {
+          reject(new AdapterExecutionCancelledError("adapter execution cancelled by external stop request"));
+        },
+        { once: true }
+      );
+    });
+    return await Promise.race([
+      executionPromise,
+      cancellationPromise,
+      new Promise<T>((_, reject) => {
+        timer = setTimeout(() => {
+          if (!executionAbort.signal.aborted) {
+            executionAbort.abort("watchdog");
+          }
+          reject(new AdapterExecutionWatchdogTimeoutError(timeoutMs));
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    if (input.externalAbortSignal && externalAbortListener) {
+      input.externalAbortSignal.removeEventListener("abort", externalAbortListener);
+    }
+  }
+}
+
+class AdapterExecutionWatchdogTimeoutError extends Error {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    super(`adapter execution timed out after ${timeoutMs}ms`);
+    this.name = "AdapterExecutionWatchdogTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+class AdapterExecutionCancelledError extends Error {
+  constructor(message = "adapter execution cancelled") {
+    super(message);
+    this.name = "AdapterExecutionCancelledError";
+  }
+}
+
+function resolveAdapterWatchdogTimeoutMs(
+  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  runtime:
+    | {
+        timeoutMs?: number;
+        interruptGraceSec?: number;
+      }
+    | undefined
+) {
+  const expectedBudgetMs = estimateProviderExecutionBudgetMs(providerType, runtime);
+  const fallback = Number(process.env.BOPO_HEARTBEAT_EXECUTION_TIMEOUT_MS ?? expectedBudgetMs);
+  if (!Number.isFinite(fallback) || fallback < 30_000) {
+    return expectedBudgetMs;
+  }
+  return Math.floor(Math.min(fallback, 15 * 60 * 1000));
+}
+
+function estimateProviderExecutionBudgetMs(
+  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  runtime:
+    | {
+        timeoutMs?: number;
+        interruptGraceSec?: number;
+        retryCount?: number;
+      }
+    | undefined
+) {
+  const perAttemptTimeoutMs = resolveRuntimeAttemptTimeoutMs(providerType, runtime?.timeoutMs);
+  const perAttemptGraceMs = Math.max(5_000, Math.floor(Math.max(0, runtime?.interruptGraceSec ?? 0) * 1000));
+  const retryCount = resolveRuntimeRetryCount(providerType, runtime?.retryCount);
+  const attemptsPerExecution = Math.max(1, Math.min(3, 1 + retryCount));
+  const executionMultiplier = providerType === "claude_code" ? 3 : 1;
+  const expectedAttempts = attemptsPerExecution * executionMultiplier;
+  const jitterBufferMs = 30_000;
+  return Math.floor(perAttemptTimeoutMs * expectedAttempts + perAttemptGraceMs * expectedAttempts + jitterBufferMs);
+}
+
+function resolveRuntimeAttemptTimeoutMs(
+  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  configuredTimeoutMs: number | undefined
+) {
+  if (Number.isFinite(configuredTimeoutMs) && (configuredTimeoutMs ?? 0) > 0) {
+    return Math.floor(configuredTimeoutMs ?? 0);
+  }
+  if (providerType === "claude_code") {
+    return 90_000;
+  }
+  if (providerType === "codex") {
+    return 5 * 60 * 1000;
+  }
+  if (providerType === "cursor") {
+    return 30_000;
+  }
+  return 45_000;
+}
+
+function resolveRuntimeRetryCount(
+  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  configuredRetryCount: number | undefined
+) {
+  if (Number.isFinite(configuredRetryCount)) {
+    return Math.max(0, Math.min(2, Math.floor(configuredRetryCount ?? 0)));
+  }
+  return providerType === "codex" ? 1 : 0;
+}
+
 function mergeRuntimeForExecution(
   runtimeFromConfig:
     | {
@@ -1019,7 +1425,7 @@ function mergeRuntimeForExecution(
   };
   return {
     ...merged,
-    // Keep system-injected BOPOHQ_* context even when state runtime carries env:{}.
+    // Keep system-injected BOPODEV_* context even when state runtime carries env:{}.
     env: {
       ...(runtimeFromState?.env ?? {}),
       ...(runtimeFromConfig?.env ?? {})
@@ -1027,6 +1433,69 @@ function mergeRuntimeForExecution(
   };
 }
 
+function registerActiveHeartbeatRun(runId: string, run: ActiveHeartbeatRun) {
+  activeHeartbeatRuns.set(runId, run);
+}
+
+function unregisterActiveHeartbeatRun(runId: string) {
+  activeHeartbeatRuns.delete(runId);
+}
+
+function clearResumeState(
+  state: AgentState & {
+    runtime?: {
+      command?: string;
+      args?: string[];
+      cwd?: string;
+      timeoutMs?: number;
+      interruptGraceSec?: number;
+      retryCount?: number;
+      retryBackoffMs?: number;
+      env?: Record<string, string>;
+      model?: string;
+      thinkingEffort?: "auto" | "low" | "medium" | "high";
+      bootstrapPrompt?: string;
+      runPolicy?: {
+        sandboxMode?: "workspace_write" | "full_access";
+        allowWebSearch?: boolean;
+      };
+    };
+  }
+) {
+  const nextState = { ...state } as AgentState & Record<string, unknown>;
+  delete nextState.sessionId;
+  delete nextState.cwd;
+  delete nextState.cursorSession;
+  return nextState as AgentState & {
+    runtime?: {
+      command?: string;
+      args?: string[];
+      cwd?: string;
+      timeoutMs?: number;
+      interruptGraceSec?: number;
+      retryCount?: number;
+      retryBackoffMs?: number;
+      env?: Record<string, string>;
+      model?: string;
+      thinkingEffort?: "auto" | "low" | "medium" | "high";
+      bootstrapPrompt?: string;
+      runPolicy?: {
+        sandboxMode?: "workspace_write" | "full_access";
+        allowWebSearch?: boolean;
+      };
+    };
+  };
+}
+
+function resolveControlPlaneEnv(runtimeEnv: Record<string, string>, suffix: string) {
+  const next = runtimeEnv[`BOPODEV_${suffix}`];
+  return hasText(next) ? (next as string) : "";
+}
+
+function resolveControlPlaneProcessEnv(suffix: string) {
+  return process.env[`BOPODEV_${suffix}`];
+}
+
 function buildHeartbeatRuntimeEnv(input: {
   companyId: string;
   agentId: string;
@@ -1044,25 +1513,27 @@ function buildHeartbeatRuntimeEnv(input: {
   });
 
   const codexApiKey = resolveCodexApiKey();
+  const claudeApiKey = resolveClaudeApiKey();
   return {
-    BOPOHQ_AGENT_ID: input.agentId,
-    BOPOHQ_COMPANY_ID: input.companyId,
-    BOPOHQ_RUN_ID: input.heartbeatRunId,
-    BOPOHQ_FORCE_MANAGED_CODEX_HOME: "false",
-    BOPOHQ_API_BASE_URL: apiBaseUrl,
-    BOPOHQ_ACTOR_TYPE: "agent",
-    BOPOHQ_ACTOR_ID: input.agentId,
-    BOPOHQ_ACTOR_COMPANIES: input.companyId,
-    BOPOHQ_ACTOR_PERMISSIONS: actorPermissions,
-    BOPOHQ_REQUEST_HEADERS_JSON: actorHeaders,
-    BOPOHQ_REQUEST_APPROVAL_DEFAULT: "true",
-    BOPOHQ_CAN_HIRE_AGENTS: input.canHireAgents ? "true" : "false",
-    ...(codexApiKey ? { OPENAI_API_KEY: codexApiKey } : {})
+    BOPODEV_AGENT_ID: input.agentId,
+    BOPODEV_COMPANY_ID: input.companyId,
+    BOPODEV_RUN_ID: input.heartbeatRunId,
+    BOPODEV_FORCE_MANAGED_CODEX_HOME: "false",
+    BOPODEV_API_BASE_URL: apiBaseUrl,
+    BOPODEV_ACTOR_TYPE: "agent",
+    BOPODEV_ACTOR_ID: input.agentId,
+    BOPODEV_ACTOR_COMPANIES: input.companyId,
+    BOPODEV_ACTOR_PERMISSIONS: actorPermissions,
+    BOPODEV_REQUEST_HEADERS_JSON: actorHeaders,
+    BOPODEV_REQUEST_APPROVAL_DEFAULT: "true",
+    BOPODEV_CAN_HIRE_AGENTS: input.canHireAgents ? "true" : "false",
+    ...(codexApiKey ? { OPENAI_API_KEY: codexApiKey } : {}),
+    ...(claudeApiKey ? { ANTHROPIC_API_KEY: claudeApiKey } : {})
   } satisfies Record<string, string>;
 }
 
 function resolveControlPlaneApiBaseUrl() {
-  const configured = process.env.BOPOHQ_API_BASE_URL ?? process.env.NEXT_PUBLIC_API_URL;
+  const configured = resolveControlPlaneProcessEnv("API_BASE_URL") ?? process.env.NEXT_PUBLIC_API_URL;
   return normalizeControlPlaneApiBaseUrl(configured) ?? "http://127.0.0.1:4020";
 }
 
@@ -1072,8 +1543,14 @@ function resolveCodexApiKey() {
   return value && value.length > 0 ? value : null;
 }
 
+function resolveClaudeApiKey() {
+  const configured = process.env.BOPO_ANTHROPIC_API_KEY ?? process.env.ANTHROPIC_API_KEY;
+  const value = configured?.trim();
+  return value && value.length > 0 ? value : null;
+}
+
 function summarizeRuntimeLaunch(
-  providerType: "claude_code" | "codex" | "http" | "shell",
+  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
   runtime:
     | {
         command?: string;
@@ -1090,13 +1567,14 @@ function summarizeRuntimeLaunch(
 ) {
   const env = runtime?.env ?? {};
   const hasOpenAiKey = typeof env.OPENAI_API_KEY === "string" && env.OPENAI_API_KEY.trim().length > 0;
+  const hasAnthropicKey = typeof env.ANTHROPIC_API_KEY === "string" && env.ANTHROPIC_API_KEY.trim().length > 0;
   const hasExplicitCodexHome = typeof env.CODEX_HOME === "string" && env.CODEX_HOME.trim().length > 0;
   const codexHomeMode =
     providerType !== "codex"
       ? null
       : hasExplicitCodexHome
         ? "explicit"
-        : hasText(env.BOPOHQ_COMPANY_ID) && hasText(env.BOPOHQ_AGENT_ID)
+        : hasText(resolveControlPlaneEnv(env, "COMPANY_ID")) && hasText(resolveControlPlaneEnv(env, "AGENT_ID"))
           ? "managed"
           : "default";
   const authMode = providerType !== "codex" ? null : hasOpenAiKey ? "api_key" : "session";
@@ -1111,9 +1589,10 @@ function summarizeRuntimeLaunch(
     codexHomeMode,
     envFlags: {
       hasOpenAiKey,
+      hasAnthropicKey,
       hasExplicitCodexHome,
-      hasControlPlaneBaseUrl: hasText(env.BOPOHQ_API_BASE_URL),
-      hasRequestHeadersJson: hasText(env.BOPOHQ_REQUEST_HEADERS_JSON)
+      hasControlPlaneBaseUrl: hasText(resolveControlPlaneEnv(env, "API_BASE_URL")),
+      hasRequestHeadersJson: hasText(resolveControlPlaneEnv(env, "REQUEST_HEADERS_JSON"))
     }
   };
 }
@@ -1142,49 +1621,44 @@ function normalizeControlPlaneApiBaseUrl(raw: string | undefined) {
 }
 
 function validateControlPlaneRuntimeEnv(runtimeEnv: Record<string, string>, runId: string) {
-  const requiredKeys = [
-    "BOPOHQ_AGENT_ID",
-    "BOPOHQ_COMPANY_ID",
-    "BOPOHQ_RUN_ID",
-    "BOPOHQ_API_BASE_URL",
-    "BOPOHQ_REQUEST_HEADERS_JSON"
-  ] as const;
-  const missingKeys = requiredKeys.filter((key) => {
-    const value = runtimeEnv[key];
-    if (typeof value !== "string" || value.trim().length === 0) {
-      return true;
-    }
-    return false;
-  });
-  const missing = [...missingKeys] as string[];
-  if (runtimeEnv.BOPOHQ_RUN_ID?.trim() && runtimeEnv.BOPOHQ_RUN_ID !== runId) {
-    missing.push("BOPOHQ_RUN_ID(mismatch)");
-  }
+  const parsed = ControlPlaneRuntimeEnvSchema.safeParse(runtimeEnv);
+  const invalidFieldPaths = parsed.success
+    ? []
+    : parsed.error.issues.map((issue) => (issue.path.length > 0 ? issue.path.join(".") : "<root>"));
+  const runtimeRunId = resolveControlPlaneEnv(runtimeEnv, "RUN_ID");
+  const mismatchError = runtimeRunId && runtimeRunId !== runId ? ["BOPODEV_RUN_ID(mismatch)"] : [];
+  const allInvalidFieldPaths = [...invalidFieldPaths, ...mismatchError];
   return {
-    ok: missing.length === 0,
-    missingKeys: missing
+    ok: allInvalidFieldPaths.length === 0,
+    validationErrorCode: parsed.success ? (mismatchError.length > 0 ? "run_id_mismatch" : null) : "invalid_control_plane_runtime_env",
+    invalidFieldPaths: allInvalidFieldPaths
   };
 }
 
 function shouldRequireControlPlanePreflight(
-  providerType: "claude_code" | "codex" | "http" | "shell",
+  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
   workItemCount: number
 ) {
   if (workItemCount < 1) {
     return false;
   }
-  return providerType === "codex" || providerType === "claude_code";
+  return (
+    providerType === "codex" ||
+    providerType === "claude_code" ||
+    providerType === "cursor" ||
+    providerType === "opencode"
+  );
 }
 
 function resolveControlPlanePreflightEnabled() {
-  const value = String(process.env.BOPOHQ_COMMUNICATION_PREFLIGHT ?? "")
+  const value = String(resolveControlPlaneProcessEnv("COMMUNICATION_PREFLIGHT") ?? "")
     .trim()
     .toLowerCase();
   return value === "1" || value === "true";
 }
 
 function resolveControlPlanePreflightTimeoutMs() {
-  const parsed = Number(process.env.BOPOHQ_COMMUNICATION_PREFLIGHT_TIMEOUT_MS ?? "1500");
+  const parsed = Number(resolveControlPlaneProcessEnv("COMMUNICATION_PREFLIGHT_TIMEOUT_MS") ?? "1500");
   if (!Number.isFinite(parsed) || parsed < 200) {
     return 1500;
   }
@@ -1193,39 +1667,27 @@ function resolveControlPlanePreflightTimeoutMs() {
 
 async function runControlPlaneConnectivityPreflight(input: {
   apiBaseUrl: string;
-  requestHeadersJson: string;
+  runtimeEnv: Record<string, string>;
   timeoutMs: number;
 }) {
   const normalizedApiBaseUrl = normalizeControlPlaneApiBaseUrl(input.apiBaseUrl);
   if (!normalizedApiBaseUrl) {
     return {
       ok: false as const,
-      message: `Invalid BOPOHQ_API_BASE_URL '${input.apiBaseUrl || "<empty>"}'.`,
+      message: `Invalid BOPODEV_API_BASE_URL '${input.apiBaseUrl || "<empty>"}'.`,
       endpoint: null
     };
   }
 
-  let requestHeaders: Record<string, string> = {};
-  try {
-    const parsed = JSON.parse(input.requestHeadersJson) as Record<string, unknown>;
-    requestHeaders = Object.fromEntries(
-      Object.entries(parsed).filter((entry): entry is [string, string] => typeof entry[1] === "string")
-    );
-  } catch {
+  const headerResolution = resolveControlPlaneHeaders(input.runtimeEnv);
+  if (!headerResolution.ok) {
     return {
       ok: false as const,
-      message: "Invalid BOPOHQ_REQUEST_HEADERS_JSON; expected JSON object of string headers.",
-      endpoint: `${normalizedApiBaseUrl}/agents`
-    };
-  }
-
-  if (!hasText(requestHeaders["x-company-id"])) {
-    return {
-      ok: false as const,
-      message: "Missing x-company-id in BOPOHQ_REQUEST_HEADERS_JSON.",
+      message: headerResolution.message,
       endpoint: `${normalizedApiBaseUrl}/agents`
     };
   }
+  const requestHeaders = headerResolution.headers;
 
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), input.timeoutMs);
@@ -1259,6 +1721,50 @@ async function runControlPlaneConnectivityPreflight(input: {
   }
 }
 
+function resolveControlPlaneHeaders(runtimeEnv: Record<string, string>):
+  | { ok: true; headers: Record<string, string> }
+  | { ok: false; message: string } {
+  const directHeaderResult = ControlPlaneRequestHeadersSchema.safeParse({
+    "x-company-id": resolveControlPlaneEnv(runtimeEnv, "COMPANY_ID"),
+    "x-actor-type": resolveControlPlaneEnv(runtimeEnv, "ACTOR_TYPE"),
+    "x-actor-id": resolveControlPlaneEnv(runtimeEnv, "ACTOR_ID"),
+    "x-actor-companies": resolveControlPlaneEnv(runtimeEnv, "ACTOR_COMPANIES"),
+    "x-actor-permissions": resolveControlPlaneEnv(runtimeEnv, "ACTOR_PERMISSIONS")
+  });
+  if (directHeaderResult.success) {
+    return { ok: true, headers: directHeaderResult.data };
+  }
+
+  const jsonHeadersRaw = resolveControlPlaneEnv(runtimeEnv, "REQUEST_HEADERS_JSON");
+  if (!hasText(jsonHeadersRaw)) {
+    return {
+      ok: false,
+      message:
+        "Missing control-plane actor headers. Provide BOPODEV_ACTOR_* vars or BOPODEV_REQUEST_HEADERS_JSON."
+    };
+  }
+
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(jsonHeadersRaw as string);
+  } catch {
+    return {
+      ok: false,
+      message: "Invalid BOPODEV_REQUEST_HEADERS_JSON; expected JSON object of string headers."
+    };
+  }
+  const jsonHeadersResult = ControlPlaneHeadersJsonSchema.safeParse(parsedJson);
+  if (!jsonHeadersResult.success) {
+    return {
+      ok: false,
+      message: `Invalid BOPODEV_REQUEST_HEADERS_JSON fields: ${jsonHeadersResult.error.issues
+        .map((issue) => issue.path.join("."))
+        .join(", ")}`
+    };
+  }
+  return { ok: true, headers: jsonHeadersResult.data };
+}
+
 function isHeartbeatDue(cronExpression: string, lastRunAt: Date | null, now: Date) {
   const normalizedNow = truncateToMinute(now);
   if (!matchesCronExpression(cronExpression, normalizedNow)) {