bopodev-api 0.1.8 → 0.1.9

package/src/services/heartbeat-service.ts

@@ -1,3 +1,4 @@
+import { mkdir } from "node:fs/promises";
 import { and, desc, eq, inArray, sql } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { resolveAdapter } from "bopodev-agent-sdk";
@@ -5,6 +6,8 @@ import type { AgentState, HeartbeatContext } from "bopodev-agent-sdk";
 import type { BopoDb } from "bopodev-db";
 import { agents, appendActivity, companies, goals, heartbeatRuns, issues, projects } from "bopodev-db";
 import { appendAuditEvent, appendCost } from "bopodev-db";
+import { parseRuntimeConfigFromAgentRow } from "../lib/agent-config";
+import { getProjectWorkspaceMap, hasText, resolveAgentFallbackWorkspace } from "../lib/workspace-policy";
 import type { RealtimeHub } from "../realtime/hub";
 import { publishOfficeOccupantForAgent } from "../realtime/office-space";
 import { checkAgentBudget } from "./budget-service";
@@ -187,8 +190,17 @@ export async function runHeartbeatForAgent(
       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;
+      };
     };
   } = {};
   let executionSummary = "";
@@ -203,6 +215,40 @@ export async function runHeartbeatForAgent(
     const parsedState = parseAgentState(agent.stateBlob);
     state = parsedState.state;
     stateParseError = parsedState.parseError;
+    const persistedRuntime = parseRuntimeConfigFromAgentRow(agent as unknown as Record<string, unknown>);
+    const heartbeatRuntimeEnv = buildHeartbeatRuntimeEnv({
+      companyId,
+      agentId: agent.id,
+      heartbeatRunId: runId,
+      canHireAgents: agent.canHireAgents
+    });
+    const runtimeFromConfig = {
+      command: persistedRuntime.runtimeCommand,
+      args: persistedRuntime.runtimeArgs,
+      cwd: persistedRuntime.runtimeCwd,
+      timeoutMs: persistedRuntime.runtimeTimeoutSec > 0 ? persistedRuntime.runtimeTimeoutSec * 1000 : undefined,
+      env: {
+        ...persistedRuntime.runtimeEnv,
+        ...heartbeatRuntimeEnv
+      },
+      model: persistedRuntime.runtimeModel,
+      thinkingEffort: persistedRuntime.runtimeThinkingEffort,
+      bootstrapPrompt: persistedRuntime.bootstrapPrompt,
+      interruptGraceSec: persistedRuntime.interruptGraceSec,
+      runPolicy: persistedRuntime.runPolicy
+    };
+    const mergedRuntime = mergeRuntimeForExecution(runtimeFromConfig, state.runtime);
+    const workspaceResolution = await resolveRuntimeWorkspaceForWorkItems(
+      db,
+      companyId,
+      agent.id,
+      workItems,
+      mergedRuntime
+    );
+    state = {
+      ...state,
+      runtime: workspaceResolution.runtime
+    };
 
     const context = await buildHeartbeatContext(db, companyId, {
       agentId,
@@ -212,9 +258,109 @@ export async function runHeartbeatForAgent(
       providerType: agent.providerType as "claude_code" | "codex" | "http" | "shell",
       heartbeatRunId: runId,
       state,
-      runtime: state.runtime,
+      runtime: workspaceResolution.runtime,
       workItems
     });
+    if (workspaceResolution.warnings.length > 0) {
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.workspace_resolution_warning",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          source: workspaceResolution.source,
+          runtimeCwd: workspaceResolution.runtime.cwd ?? null,
+          warnings: workspaceResolution.warnings
+        }
+      });
+      for (const issueId of issueIds) {
+        await appendActivity(db, {
+          companyId,
+          issueId,
+          actorType: "system",
+          eventType: "issue.workspace_fallback",
+          payload: {
+            heartbeatRunId: runId,
+            agentId,
+            source: workspaceResolution.source,
+            warnings: workspaceResolution.warnings
+          }
+        });
+      }
+    }
+
+    const controlPlaneEnvValidation = validateControlPlaneRuntimeEnv(
+      workspaceResolution.runtime.env ?? {},
+      runId
+    );
+    if (!controlPlaneEnvValidation.ok) {
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.control_plane_env_invalid",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          providerType: agent.providerType,
+          missingKeys: controlPlaneEnvValidation.missingKeys
+        }
+      });
+      throw new Error(
+        `Control-plane runtime env is incomplete. Missing keys: ${controlPlaneEnvValidation.missingKeys.join(", ")}`
+      );
+    }
+
+    if (
+      resolveControlPlanePreflightEnabled() &&
+      shouldRequireControlPlanePreflight(agent.providerType as "claude_code" | "codex" | "http" | "shell", workItems.length)
+    ) {
+      const preflight = await runControlPlaneConnectivityPreflight({
+        apiBaseUrl: workspaceResolution.runtime.env?.BOPOHQ_API_BASE_URL ?? "",
+        requestHeadersJson: workspaceResolution.runtime.env?.BOPOHQ_REQUEST_HEADERS_JSON ?? "",
+        timeoutMs: resolveControlPlanePreflightTimeoutMs()
+      });
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: preflight.ok ? "heartbeat.control_plane_preflight_passed" : "heartbeat.control_plane_preflight_failed",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          providerType: agent.providerType,
+          ...preflight
+        }
+      });
+      if (!preflight.ok) {
+        throw new Error(`Control-plane connectivity preflight failed: ${preflight.message}`);
+      }
+    }
+
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.runtime_launch",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: {
+        agentId,
+        runtime: summarizeRuntimeLaunch(
+          agent.providerType as "claude_code" | "codex" | "http" | "shell",
+          workspaceResolution.runtime
+        ),
+        diagnostics: {
+          requestId: options?.requestId ?? null,
+          trigger: options?.trigger ?? "manual"
+        }
+      }
+    });
 
     const execution = await adapter.execute(context);
     executionSummary = execution.summary;
@@ -251,7 +397,15 @@ export async function runHeartbeatForAgent(
         .where(and(eq(agents.companyId, companyId), eq(agents.id, agentId)));
     }
 
-    if (issueIds.length > 0 && execution.status === "ok") {
+    const shouldAdvanceIssuesToReview = shouldPromoteIssuesToReview({
+      summary: execution.summary,
+      tokenInput: execution.tokenInput,
+      tokenOutput: execution.tokenOutput,
+      usdCost: execution.usdCost,
+      trace: executionTrace
+    });
+
+    if (issueIds.length > 0 && execution.status === "ok" && shouldAdvanceIssuesToReview) {
       await db
         .update(issues)
         .set({ status: "in_review", updatedAt: new Date() })
@@ -266,6 +420,35 @@ export async function runHeartbeatForAgent(
           payload: { heartbeatRunId: runId, agentId }
         });
       }
+    } else if (issueIds.length > 0 && execution.status === "ok") {
+      for (const issueId of issueIds) {
+        await appendActivity(db, {
+          companyId,
+          issueId,
+          actorType: "system",
+          eventType: "issue.review_gate_blocked",
+          payload: { heartbeatRunId: runId, agentId, reason: "insufficient_real_execution_evidence" }
+        });
+      }
+      await appendAuditEvent(db, {
+        companyId,
+        actorType: "system",
+        eventType: "heartbeat.review_gate_blocked",
+        entityType: "heartbeat_run",
+        entityId: runId,
+        correlationId: options?.requestId ?? runId,
+        payload: {
+          agentId,
+          issueIds,
+          reason: "insufficient_real_execution_evidence",
+          summary: execution.summary,
+          usage: {
+            tokenInput: execution.tokenInput,
+            tokenOutput: execution.tokenOutput,
+            usdCost: execution.usdCost
+          }
+        }
+      });
     }
 
     await db
@@ -291,7 +474,8 @@ export async function runHeartbeatForAgent(
         usage: {
           tokenInput: execution.tokenInput,
           tokenOutput: execution.tokenOutput,
-          usdCost: execution.usdCost
+          usdCost: execution.usdCost,
+          source: readTraceString(execution.trace, "usageSource") ?? "unknown"
         },
         trace: execution.trace ?? null,
         diagnostics: {
@@ -324,6 +508,9 @@ export async function runHeartbeatForAgent(
         issueIds,
         errorType: classified.type,
         errorMessage: classified.message,
+        usage: {
+          source: readTraceString(executionTrace, "usageSource") ?? "unknown"
+        },
         trace: executionTrace,
         diagnostics: {
           stateParseError,
@@ -613,8 +800,17 @@ function parseAgentState(stateBlob: string | null) {
           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;
+          };
         };
       },
       parseError: null
@@ -638,6 +834,137 @@ function classifyHeartbeatError(error: unknown) {
   return { type: "unknown", message };
 }
 
+function shouldPromoteIssuesToReview(input: {
+  summary: string;
+  tokenInput: number;
+  tokenOutput: number;
+  usdCost: number;
+  trace: unknown;
+}) {
+  return !isBootstrapDemoSummary(input.summary) && hasRealExecutionEvidence(input);
+}
+
+function isBootstrapDemoSummary(summary: string) {
+  const normalized = summary.trim().toLowerCase();
+  return normalized === "ceo bootstrap heartbeat" || normalized.startsWith("ceo bootstrap heartbeat ");
+}
+
+function hasRealExecutionEvidence(input: {
+  tokenInput: number;
+  tokenOutput: number;
+  usdCost: number;
+  trace: unknown;
+}) {
+  if (input.tokenInput > 0 || input.tokenOutput > 0 || input.usdCost > 0) {
+    return true;
+  }
+  const stdoutPreview = readTraceString(input.trace, "stdoutPreview");
+  if (!stdoutPreview) {
+    return false;
+  }
+  return !looksLikeEchoedPrompt(stdoutPreview);
+}
+
+function looksLikeEchoedPrompt(stdoutPreview: string) {
+  const normalized = stdoutPreview.toLowerCase();
+  return (
+    normalized.includes("execution directives:") &&
+    normalized.includes("at the end of your response, include exactly one json object on a single line:")
+  );
+}
+
+function readTraceString(trace: unknown, key: string) {
+  if (!trace || typeof trace !== "object") {
+    return null;
+  }
+  const value = (trace as Record<string, unknown>)[key];
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+async function resolveRuntimeWorkspaceForWorkItems(
+  db: BopoDb,
+  companyId: string,
+  agentId: string,
+  workItems: Array<{ project_id: string }>,
+  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;
+        };
+      }
+    | undefined
+) {
+  const normalizedRuntimeCwd = runtime?.cwd?.trim();
+  const warnings: string[] = [];
+  const projectIds = Array.from(new Set(workItems.map((item) => item.project_id)));
+  const projectWorkspaceMap = await getProjectWorkspaceMap(db, companyId, projectIds);
+
+  let selectedProjectWorkspace: string | null = null;
+  for (const projectId of projectIds) {
+    const projectWorkspace = projectWorkspaceMap.get(projectId) ?? null;
+    if (hasText(projectWorkspace)) {
+      selectedProjectWorkspace = projectWorkspace;
+      break;
+    }
+  }
+
+  if (selectedProjectWorkspace) {
+    await mkdir(selectedProjectWorkspace, { recursive: true });
+    if (hasText(normalizedRuntimeCwd) && normalizedRuntimeCwd !== selectedProjectWorkspace) {
+      warnings.push(
+        `Runtime cwd '${normalizedRuntimeCwd}' was overridden to project workspace '${selectedProjectWorkspace}' for assigned work.`
+      );
+    }
+    return {
+      source: "project_workspace",
+      warnings,
+      runtime: {
+        ...runtime,
+        cwd: selectedProjectWorkspace
+      }
+    };
+  }
+
+  if (projectIds.length > 0) {
+    warnings.push("Assigned project has no local workspace path configured. Falling back to agent workspace.");
+  }
+
+  if (hasText(normalizedRuntimeCwd)) {
+    return {
+      source: "agent_runtime",
+      warnings,
+      runtime: {
+        ...runtime,
+        cwd: normalizedRuntimeCwd
+      }
+    };
+  }
+
+  const fallbackWorkspace = resolveAgentFallbackWorkspace(companyId, agentId);
+  await mkdir(fallbackWorkspace, { recursive: true });
+  warnings.push(`Runtime cwd was not configured. Falling back to '${fallbackWorkspace}'.`);
+  return {
+    source: "agent_fallback",
+    warnings,
+    runtime: {
+      ...runtime,
+      cwd: fallbackWorkspace
+    }
+  };
+}
+
 function resolveStaleRunThresholdMs() {
   const parsed = Number(process.env.BOPO_HEARTBEAT_STALE_RUN_MS ?? 10 * 60 * 1000);
   if (!Number.isFinite(parsed) || parsed < 1_000) {
@@ -646,6 +973,292 @@ function resolveStaleRunThresholdMs() {
   return parsed;
 }
 
+function mergeRuntimeForExecution(
+  runtimeFromConfig:
+    | {
+        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;
+        };
+      }
+    | undefined,
+  runtimeFromState:
+    | {
+        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;
+        };
+      }
+    | undefined
+) {
+  const merged = {
+    ...(runtimeFromConfig ?? {}),
+    ...(runtimeFromState ?? {})
+  };
+  return {
+    ...merged,
+    // Keep system-injected BOPOHQ_* context even when state runtime carries env:{}.
+    env: {
+      ...(runtimeFromState?.env ?? {}),
+      ...(runtimeFromConfig?.env ?? {})
+    }
+  };
+}
+
+function buildHeartbeatRuntimeEnv(input: {
+  companyId: string;
+  agentId: string;
+  heartbeatRunId: string;
+  canHireAgents: boolean;
+}) {
+  const apiBaseUrl = resolveControlPlaneApiBaseUrl();
+  const actorPermissions = ["issues:write", "agents:write"].join(",");
+  const actorHeaders = JSON.stringify({
+    "x-company-id": input.companyId,
+    "x-actor-type": "agent",
+    "x-actor-id": input.agentId,
+    "x-actor-companies": input.companyId,
+    "x-actor-permissions": actorPermissions
+  });
+
+  const codexApiKey = resolveCodexApiKey();
+  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 } : {})
+  } satisfies Record<string, string>;
+}
+
+function resolveControlPlaneApiBaseUrl() {
+  const configured = process.env.BOPOHQ_API_BASE_URL ?? process.env.NEXT_PUBLIC_API_URL;
+  return normalizeControlPlaneApiBaseUrl(configured) ?? "http://127.0.0.1:4020";
+}
+
+function resolveCodexApiKey() {
+  const configured = process.env.BOPO_OPENAI_API_KEY ?? process.env.OPENAI_API_KEY;
+  const value = configured?.trim();
+  return value && value.length > 0 ? value : null;
+}
+
+function summarizeRuntimeLaunch(
+  providerType: "claude_code" | "codex" | "http" | "shell",
+  runtime:
+    | {
+        command?: string;
+        args?: string[];
+        cwd?: string;
+        timeoutMs?: number;
+        env?: Record<string, string>;
+        runPolicy?: {
+          sandboxMode?: "workspace_write" | "full_access";
+          allowWebSearch?: boolean;
+        };
+      }
+    | undefined
+) {
+  const env = runtime?.env ?? {};
+  const hasOpenAiKey = typeof env.OPENAI_API_KEY === "string" && env.OPENAI_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)
+          ? "managed"
+          : "default";
+  const authMode = providerType !== "codex" ? null : hasOpenAiKey ? "api_key" : "session";
+
+  return {
+    command: runtime?.command ?? null,
+    args: runtime?.args ?? [],
+    cwd: runtime?.cwd ?? null,
+    timeoutMs: runtime?.timeoutMs ?? null,
+    runPolicy: runtime?.runPolicy ?? null,
+    authMode,
+    codexHomeMode,
+    envFlags: {
+      hasOpenAiKey,
+      hasExplicitCodexHome,
+      hasControlPlaneBaseUrl: hasText(env.BOPOHQ_API_BASE_URL),
+      hasRequestHeadersJson: hasText(env.BOPOHQ_REQUEST_HEADERS_JSON)
+    }
+  };
+}
+
+function normalizeControlPlaneApiBaseUrl(raw: string | undefined) {
+  const value = raw?.trim();
+  if (!value) {
+    return null;
+  }
+  try {
+    const url = new URL(value);
+    if (!url.protocol || (url.protocol !== "http:" && url.protocol !== "https:")) {
+      return null;
+    }
+    // Keep local addresses canonical to avoid split diagnostics between localhost/127.0.0.1.
+    if (url.hostname === "localhost") {
+      url.hostname = "127.0.0.1";
+    }
+    url.pathname = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+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)");
+  }
+  return {
+    ok: missing.length === 0,
+    missingKeys: missing
+  };
+}
+
+function shouldRequireControlPlanePreflight(
+  providerType: "claude_code" | "codex" | "http" | "shell",
+  workItemCount: number
+) {
+  if (workItemCount < 1) {
+    return false;
+  }
+  return providerType === "codex" || providerType === "claude_code";
+}
+
+function resolveControlPlanePreflightEnabled() {
+  const value = String(process.env.BOPOHQ_COMMUNICATION_PREFLIGHT ?? "")
+    .trim()
+    .toLowerCase();
+  return value === "1" || value === "true";
+}
+
+function resolveControlPlanePreflightTimeoutMs() {
+  const parsed = Number(process.env.BOPOHQ_COMMUNICATION_PREFLIGHT_TIMEOUT_MS ?? "1500");
+  if (!Number.isFinite(parsed) || parsed < 200) {
+    return 1500;
+  }
+  return Math.floor(parsed);
+}
+
+async function runControlPlaneConnectivityPreflight(input: {
+  apiBaseUrl: string;
+  requestHeadersJson: string;
+  timeoutMs: number;
+}) {
+  const normalizedApiBaseUrl = normalizeControlPlaneApiBaseUrl(input.apiBaseUrl);
+  if (!normalizedApiBaseUrl) {
+    return {
+      ok: false as const,
+      message: `Invalid BOPOHQ_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 {
+    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.",
+      endpoint: `${normalizedApiBaseUrl}/agents`
+    };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), input.timeoutMs);
+  const endpoint = `${normalizedApiBaseUrl}/agents`;
+  try {
+    const response = await fetch(endpoint, {
+      method: "GET",
+      headers: requestHeaders,
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return {
+        ok: false as const,
+        message: `Control plane responded ${response.status} ${response.statusText}.`,
+        endpoint
+      };
+    }
+    return {
+      ok: true as const,
+      message: "Control-plane preflight passed.",
+      endpoint
+    };
+  } catch (error) {
+    return {
+      ok: false as const,
+      message: String(error),
+      endpoint
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 function isHeartbeatDue(cronExpression: string, lastRunAt: Date | null, now: Date) {
   const normalizedNow = truncateToMinute(now);
   if (!matchesCronExpression(cronExpression, normalizedNow)) {