bopodev-api 0.1.28 → 0.1.30

package/src/services/heartbeat-service/index.ts

@@ -0,0 +1,5 @@
+export { claimIssuesForAgent, releaseClaimedIssues } from "./claims";
+export { findPendingProjectBudgetOverrideBlocksForAgent } from "./budget-override";
+export { stopHeartbeatRun } from "./stop";
+export { runHeartbeatSweep } from "./sweep";
+export { runHeartbeatForAgent } from "./heartbeat-run";

package/src/services/heartbeat-service/stop.ts

@@ -0,0 +1,90 @@
+import { appendAuditEvent } from "bopodev-db";
+import { and, eq, heartbeatRuns } from "bopodev-db";
+import type { BopoDb } from "bopodev-db";
+import type { RealtimeHub } from "../../realtime/hub";
+import { getActiveHeartbeatRun } from "./active-runs";
+import { publishHeartbeatRunStatus } from "./heartbeat-realtime";
+import type { HeartbeatRunTrigger } from "./types";
+
+export async function stopHeartbeatRun(
+  db: BopoDb,
+  companyId: string,
+  runId: string,
+  options?: { requestId?: string; actorId?: string; trigger?: HeartbeatRunTrigger; realtimeHub?: RealtimeHub }
+) {
+  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 = getActiveHeartbeatRun(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 {
+    const finishedAt = new Date();
+    await db
+      .update(heartbeatRuns)
+      .set({
+        status: "failed",
+        finishedAt,
+        message: "Heartbeat cancelled by stop request."
+      })
+      .where(and(eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.id, runId)));
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "failed",
+      message: "Heartbeat cancelled by stop request.",
+      finishedAt
+    });
+  }
+  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 };
+}

package/src/services/heartbeat-service/sweep.ts

@@ -0,0 +1,145 @@
+import { appendAuditEvent } from "bopodev-db";
+import { agents, eq, heartbeatRuns, max } from "bopodev-db";
+import type { BopoDb } from "bopodev-db";
+import type { RealtimeHub } from "../../realtime/hub";
+import { findPendingProjectBudgetOverrideBlocksForAgent } from "./budget-override";
+import { isHeartbeatDue } from "./cron";
+
+export async function runHeartbeatSweep(
+  db: BopoDb,
+  companyId: string,
+  options?: { requestId?: string; realtimeHub?: RealtimeHub }
+) {
+  const companyAgents = await db.select().from(agents).where(eq(agents.companyId, companyId));
+  const latestRunByAgent = await listLatestRunByAgent(db, companyId);
+
+  const now = new Date();
+  const enqueuedJobIds: string[] = [];
+  const dueAgents: Array<{ id: string }> = [];
+  let skippedNotDue = 0;
+  let skippedStatus = 0;
+  let skippedBudgetBlocked = 0;
+  let failedStarts = 0;
+  const sweepStartedAt = Date.now();
+  for (const agent of companyAgents) {
+    if (agent.status !== "idle" && agent.status !== "running") {
+      skippedStatus += 1;
+      continue;
+    }
+    if (!isHeartbeatDue(agent.heartbeatCron, latestRunByAgent.get(agent.id) ?? null, now)) {
+      skippedNotDue += 1;
+      continue;
+    }
+    const blockedProjectIds = await findPendingProjectBudgetOverrideBlocksForAgent(db, companyId, agent.id);
+    if (blockedProjectIds.length > 0) {
+      skippedBudgetBlocked += 1;
+      continue;
+    }
+    dueAgents.push({ id: agent.id });
+  }
+  const sweepConcurrency = resolveHeartbeatSweepConcurrency(dueAgents.length);
+  const queueModule = await import("../heartbeat-queue-service");
+  await runWithConcurrency(dueAgents, sweepConcurrency, async (agent) => {
+    try {
+      const job = await queueModule.enqueueHeartbeatQueueJob(db, {
+        companyId,
+        agentId: agent.id,
+        jobType: "scheduler",
+        priority: 80,
+        idempotencyKey: options?.requestId ? `scheduler:${agent.id}:${options.requestId}` : null,
+        payload: {}
+      });
+      enqueuedJobIds.push(job.id);
+      queueModule.triggerHeartbeatQueueWorker(db, companyId, {
+        requestId: options?.requestId,
+        realtimeHub: options?.realtimeHub
+      });
+    } catch {
+      failedStarts += 1;
+    }
+  });
+  await appendAuditEvent(db, {
+    companyId,
+    actorType: "system",
+    eventType: "heartbeat.sweep.completed",
+    entityType: "company",
+    entityId: companyId,
+    correlationId: options?.requestId ?? null,
+    payload: {
+      runIds: enqueuedJobIds,
+      startedCount: enqueuedJobIds.length,
+      dueCount: dueAgents.length,
+      failedStarts,
+      skippedStatus,
+      skippedNotDue,
+      skippedBudgetBlocked,
+      concurrency: sweepConcurrency,
+      elapsedMs: Date.now() - sweepStartedAt,
+      requestId: options?.requestId ?? null
+    }
+  });
+  return enqueuedJobIds;
+}
+
+async function listLatestRunByAgent(db: BopoDb, companyId: string) {
+  const rows = await db
+    .select({
+      agentId: heartbeatRuns.agentId,
+      latestStartedAt: max(heartbeatRuns.startedAt)
+    })
+    .from(heartbeatRuns)
+    .where(eq(heartbeatRuns.companyId, companyId))
+    .groupBy(heartbeatRuns.agentId);
+  const latestRunByAgent = new Map<string, Date>();
+  for (const row of rows) {
+    const startedAt = coerceDate(row.latestStartedAt);
+    if (!startedAt) {
+      continue;
+    }
+    latestRunByAgent.set(row.agentId, startedAt);
+  }
+  return latestRunByAgent;
+}
+
+function coerceDate(value: unknown) {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value;
+  }
+  if (typeof value === "string" || typeof value === "number") {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+  }
+  return null;
+}
+
+function resolveHeartbeatSweepConcurrency(dueAgentsCount: number) {
+  const configured = Number(process.env.BOPO_HEARTBEAT_SWEEP_CONCURRENCY ?? "4");
+  const fallback = 4;
+  const normalized = Number.isFinite(configured) ? Math.floor(configured) : fallback;
+  if (normalized < 1) {
+    return 1;
+  }
+  const bounded = Math.min(normalized, 16);
+  return Math.min(bounded, Math.max(1, dueAgentsCount));
+}
+
+async function runWithConcurrency<T>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T, index: number) => Promise<void>
+) {
+  if (items.length === 0) {
+    return;
+  }
+  const workerCount = Math.max(1, Math.min(Math.floor(concurrency), items.length));
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (cursor < items.length) {
+        const index = cursor;
+        cursor += 1;
+        await worker(items[index] as T, index);
+      }
+    })
+  );
+}

package/src/services/heartbeat-service/types.ts

@@ -0,0 +1,66 @@
+import type { RunCompletionReason } from "bopodev-contracts";
+
+export type HeartbeatRunTrigger = "manual" | "scheduler";
+export type HeartbeatRunMode = "default" | "resume" | "redo";
+export type HeartbeatProviderType =
+  | "claude_code"
+  | "codex"
+  | "cursor"
+  | "opencode"
+  | "gemini_cli"
+  | "openai_api"
+  | "anthropic_api"
+  | "openclaw_gateway"
+  | "http"
+  | "shell";
+
+export type ActiveHeartbeatRun = {
+  companyId: string;
+  agentId: string;
+  abortController: AbortController;
+  cancelReason?: string | null;
+  cancelRequestedAt?: string | null;
+  cancelRequestedBy?: string | null;
+};
+
+export type HeartbeatWakeContext = {
+  reason?: string | null;
+  commentId?: string | null;
+  commentBody?: string | null;
+  issueIds?: string[];
+};
+
+export 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";
+};
+
+export 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;
+  };
+};
+
+export type RunTerminalPresentation = {
+  internalStatus: "completed" | "failed" | "skipped";
+  publicStatus: "completed" | "failed";
+  completionReason: RunCompletionReason;
+};
+
+export type HeartbeatIdlePolicy = "full" | "skip_adapter" | "micro_prompt";

package/src/services/memory-file-service.ts

@@ -106,6 +106,7 @@ export async function persistHeartbeatMemory(input: {
   goalContext?: {
     companyGoals?: string[];
     projectGoals?: string[];
+    agentGoals?: string[];
   };
 }): Promise<PersistedHeartbeatMemory> {
   const memoryRoot = resolveAgentMemoryRootPath(input.companyId, input.agentId);
@@ -237,6 +238,7 @@ function deriveCandidateFacts(
     goalContext?: {
       companyGoals?: string[];
       projectGoals?: string[];
+      agentGoals?: string[];
     };
   }
 ): MemoryCandidateFact[] {
@@ -575,6 +577,7 @@ function deriveImpactTags(
   goalContext?: {
     companyGoals?: string[];
     projectGoals?: string[];
+    agentGoals?: string[];
   }
 ) {
   const tags = new Set<string>();
@@ -595,7 +598,9 @@ function deriveImpactTags(
   if (scoreTextMatch(fact, missionTokens) > 0) {
     tags.add("mission");
   }
-  const goalTokens = tokenize([...(goalContext?.companyGoals ?? []), ...(goalContext?.projectGoals ?? [])].join(" "));
+  const goalTokens = tokenize(
+    [...(goalContext?.companyGoals ?? []), ...(goalContext?.projectGoals ?? []), ...(goalContext?.agentGoals ?? [])].join(" ")
+  );
   if (scoreTextMatch(fact, goalTokens) > 0) {
     tags.add("goal");
   }
@@ -608,10 +613,13 @@ function computeMissionAlignmentScore(
   goalContext?: {
     companyGoals?: string[];
     projectGoals?: string[];
+    agentGoals?: string[];
   }
 ) {
   const missionTokens = tokenize(mission ?? "");
-  const goalTokens = tokenize([...(goalContext?.companyGoals ?? []), ...(goalContext?.projectGoals ?? [])].join(" "));
+  const goalTokens = tokenize(
+    [...(goalContext?.companyGoals ?? []), ...(goalContext?.projectGoals ?? []), ...(goalContext?.agentGoals ?? [])].join(" ")
+  );
   const missionScore = scoreTextMatch(summary, missionTokens);
   const goalScore = scoreTextMatch(summary, goalTokens);
   return Math.min(1, missionScore * 0.55 + goalScore * 0.45);

package/src/services/template-apply-service.ts

@@ -62,6 +62,7 @@ export async function applyTemplateManifest(
       role: resolveAgentRoleText(agent.role, agent.roleKey, agent.title),
       roleKey: normalizeRoleKey(agent.roleKey),
       title: normalizeTitle(agent.title),
+      capabilities: normalizeCapabilities(agent.capabilities),
       name: agent.name,
       providerType: agent.providerType,
       heartbeatCron: agent.heartbeatCron,
@@ -152,6 +153,11 @@ function normalizeTitle(input: string | null | undefined) {
   return normalized ? normalized : null;
 }
 
+function normalizeCapabilities(input: string | null | undefined) {
+  const normalized = input?.trim();
+  return normalized ? normalized : null;
+}
+
 function resolveAgentRoleText(
   legacyRole: string | undefined,
   roleKeyInput: string | undefined,

package/src/services/template-catalog.ts

@@ -9,7 +9,8 @@ import {
   createTemplate,
   createTemplateVersion,
   getTemplateBySlug,
-  getTemplateVersionByVersion
+  getTemplateVersionByVersion,
+  updateTemplate
 } from "bopodev-db";
 
 type BuiltinTemplateDefinition = {
@@ -28,7 +29,7 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
     slug: "founder-startup-basic",
     name: "Founder Startup Basic",
     description: "Baseline operating company for solo founders launching and shipping with AI agents.",
-    version: "1.0.0",
+    version: "1.0.1",
     status: "published",
     visibility: "company",
     variables: [
@@ -78,6 +79,10 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
         {
           key: "founder-ceo",
           role: "CEO",
+          roleKey: "ceo",
+          title: "Founder CEO",
+          capabilities:
+            "Sets company priorities, runs leadership cadence, hires and coordinates agents toward mission outcomes.",
           name: "Founder CEO",
           providerType: "codex",
           heartbeatCron: "*/15 * * * *",
@@ -119,6 +124,10 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
         {
           key: "founding-engineer",
           role: "Founding Engineer",
+          roleKey: "engineer",
+          title: "Founding Engineer",
+          capabilities:
+            "Ships product improvements with small reviewable changes, tests, and clear handoffs to stakeholders.",
           name: "Founding Engineer",
           managerAgentKey: "founder-ceo",
           providerType: "codex",
@@ -152,6 +161,10 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
         {
           key: "growth-operator",
           role: "Growth Operator",
+          roleKey: "general",
+          title: "Growth Operator",
+          capabilities:
+            "Runs growth experiments, measures funnel impact, and feeds learnings back to leadership with clear next steps.",
           name: "Growth Operator",
           managerAgentKey: "founder-ceo",
           providerType: "codex",
@@ -225,7 +238,7 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
     slug: "marketing-content-engine",
     name: "Marketing Content Engine",
     description: "Content marketing operating template for publishing, distribution, and analytics loops.",
-    version: "1.0.0",
+    version: "1.0.1",
     status: "published",
     visibility: "company",
     variables: [
@@ -276,6 +289,10 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
         {
           key: "head-of-marketing",
           role: "Head of Marketing",
+          roleKey: "cmo",
+          title: "Head of Marketing",
+          capabilities:
+            "Owns marketing narrative, cross-functional alignment, and weekly performance decisions for pipeline growth.",
           name: "Head of Marketing",
           providerType: "codex",
           heartbeatCron: "*/20 * * * *",
@@ -308,6 +325,10 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
         {
           key: "content-strategist",
           role: "Content Strategist",
+          roleKey: "general",
+          title: "Content Strategist",
+          capabilities:
+            "Builds editorial calendars, briefs, and topic architecture tied to audience segments and revenue goals.",
           name: "Content Strategist",
           managerAgentKey: "head-of-marketing",
           providerType: "codex",
@@ -337,6 +358,10 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
         {
           key: "content-writer",
           role: "Content Writer",
+          roleKey: "general",
+          title: "Content Writer",
+          capabilities:
+            "Produces channel-ready drafts, headline and CTA options, and repurposing notes aligned to campaign intent.",
           name: "Content Writer",
           managerAgentKey: "head-of-marketing",
           providerType: "codex",
@@ -367,6 +392,10 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
         {
           key: "distribution-manager",
           role: "Distribution Manager",
+          roleKey: "general",
+          title: "Distribution Manager",
+          capabilities:
+            "Distributes and repurposes assets across channels with tracking discipline and weekly performance reporting.",
           name: "Distribution Manager",
           managerAgentKey: "head-of-marketing",
           providerType: "codex",
@@ -482,6 +511,11 @@ export async function ensureCompanyBuiltinTemplateDefaults(db: BopoDb, companyId
         version: definition.version,
         manifestJson: JSON.stringify(manifest)
       });
+      await updateTemplate(db, {
+        companyId,
+        id: template.id,
+        currentVersion: definition.version
+      });
     }
   }
 }

package/src/shutdown/graceful-shutdown.ts

@@ -0,0 +1,77 @@
+import type { Server } from "node:http";
+import type { RealtimeHub } from "../realtime/hub";
+import { beginIssueCommentDispatchShutdown, waitForIssueCommentDispatchDrain } from "../services/comment-recipient-dispatch-service";
+import { beginHeartbeatQueueShutdown, waitForHeartbeatQueueDrain } from "../services/heartbeat-queue-service";
+
+export async function closeDatabaseClient(client: unknown) {
+  if (!client || typeof client !== "object") {
+    return;
+  }
+  const closeFn = (client as { close?: unknown }).close;
+  if (typeof closeFn !== "function") {
+    return;
+  }
+  await (closeFn as () => Promise<void>)();
+}
+
+export function attachGracefulShutdownHandlers(options: {
+  server: Server;
+  realtimeHub: RealtimeHub;
+  dbClient: unknown;
+  scheduler?: { stop: () => Promise<void> };
+}) {
+  const { server, realtimeHub, dbClient, scheduler } = options;
+  let shutdownInFlight: Promise<void> | null = null;
+
+  function shutdown(signal: string) {
+    const shutdownTimeoutMs = Number(process.env.BOPO_SHUTDOWN_TIMEOUT_MS ?? 15_000);
+    const forcedExit = setTimeout(() => {
+      // eslint-disable-next-line no-console
+      console.error(`[shutdown] timed out after ${shutdownTimeoutMs}ms; forcing exit.`);
+      process.exit(process.exitCode ?? 1);
+    }, shutdownTimeoutMs);
+    forcedExit.unref();
+    shutdownInFlight ??= (async () => {
+      // eslint-disable-next-line no-console
+      console.log(`[shutdown] ${signal} — draining HTTP/background work before closing the embedded database…`);
+      beginHeartbeatQueueShutdown();
+      beginIssueCommentDispatchShutdown();
+      await Promise.allSettled([
+        scheduler?.stop() ?? Promise.resolve(),
+        new Promise<void>((resolve, reject) => {
+          server.close((err) => {
+            if (err) {
+              reject(err);
+              return;
+            }
+            resolve();
+          });
+        })
+      ]);
+      await Promise.allSettled([waitForHeartbeatQueueDrain(), waitForIssueCommentDispatchDrain()]);
+      try {
+        await realtimeHub.close();
+      } catch (closeError) {
+        // eslint-disable-next-line no-console
+        console.error("[shutdown] realtime hub close error", closeError);
+      }
+      try {
+        await closeDatabaseClient(dbClient);
+      } catch (closeDbError) {
+        // eslint-disable-next-line no-console
+        console.error("[shutdown] database close error", closeDbError);
+      }
+      // eslint-disable-next-line no-console
+      console.log("[shutdown] clean exit");
+      process.exitCode = 0;
+    })().catch((error) => {
+      // eslint-disable-next-line no-console
+      console.error("[shutdown] failed", error);
+      process.exitCode = 1;
+    });
+    return shutdownInFlight;
+  }
+
+  process.once("SIGINT", () => void shutdown("SIGINT"));
+  process.once("SIGTERM", () => void shutdown("SIGTERM"));
+}

package/src/startup/database.ts

@@ -0,0 +1,41 @@
+import { bootstrapDatabase, resolveDefaultDbPath } from "bopodev-db";
+
+export function isProbablyDatabaseStartupError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  const cause = error instanceof Error ? error.cause : undefined;
+  const causeMessage = cause instanceof Error ? cause.message : String(cause ?? "");
+  return (
+    message.includes("database") ||
+    message.includes("postgres") ||
+    message.includes("migration") ||
+    causeMessage.includes("postgres") ||
+    causeMessage.includes("connection")
+  );
+}
+
+export type BootstrappedDb = Awaited<ReturnType<typeof bootstrapDatabase>>;
+
+export async function bootstrapDatabaseWithStartupLogging(dbPath: string | undefined): Promise<BootstrappedDb> {
+  const usingExternalDatabase = Boolean(process.env.DATABASE_URL?.trim());
+  const effectiveDbPath = dbPath ?? resolveDefaultDbPath();
+  try {
+    return await bootstrapDatabase(dbPath);
+  } catch (error) {
+    if (isProbablyDatabaseStartupError(error)) {
+      // eslint-disable-next-line no-console
+      console.error("[startup] Database bootstrap failed before the API could start.");
+      if (usingExternalDatabase) {
+        // eslint-disable-next-line no-console
+        console.error("[startup] Check DATABASE_URL connectivity, permissions, and migration state.");
+      } else {
+        // eslint-disable-next-line no-console
+        console.error(`[startup] Embedded Postgres data path: ${effectiveDbPath}`);
+        // eslint-disable-next-line no-console
+        console.error(
+          "[startup] Recovery: stop all API/node processes using this DB, back up the path above, delete the directory if it is corrupted, then restart. Or set BOPO_DB_PATH to a fresh path."
+        );
+      }
+    }
+    throw error;
+  }
+}

package/src/startup/deployment-validation.ts

@@ -0,0 +1,37 @@
+import { isAuthenticatedMode, type DeploymentMode } from "../security/deployment-mode";
+
+export function validateDeploymentConfiguration(
+  deploymentMode: DeploymentMode,
+  allowedOrigins: string[],
+  allowedHostnames: string[],
+  publicBaseUrl: URL | null
+) {
+  if (deploymentMode === "authenticated_public" && !publicBaseUrl) {
+    throw new Error("BOPO_PUBLIC_BASE_URL is required in authenticated_public mode.");
+  }
+  if (isAuthenticatedMode(deploymentMode) && process.env.BOPO_AUTH_TOKEN_SECRET?.trim() === "") {
+    throw new Error("BOPO_AUTH_TOKEN_SECRET must not be empty when set.");
+  }
+  if (isAuthenticatedMode(deploymentMode) && !process.env.BOPO_AUTH_TOKEN_SECRET?.trim()) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[startup] BOPO_AUTH_TOKEN_SECRET is not set. Authenticated modes will require BOPO_TRUST_ACTOR_HEADERS=1 behind a trusted proxy."
+    );
+  }
+  if (
+    isAuthenticatedMode(deploymentMode) &&
+    process.env.BOPO_TRUST_ACTOR_HEADERS !== "1" &&
+    !process.env.BOPO_AUTH_TOKEN_SECRET?.trim()
+  ) {
+    throw new Error(
+      "Authenticated mode requires either BOPO_AUTH_TOKEN_SECRET (token identity) or BOPO_TRUST_ACTOR_HEADERS=1 (trusted proxy headers)."
+    );
+  }
+  if (isAuthenticatedMode(deploymentMode) && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK === "1") {
+    throw new Error("BOPO_ALLOW_LOCAL_BOARD_FALLBACK cannot be enabled in authenticated modes.");
+  }
+  // eslint-disable-next-line no-console
+  console.log(
+    `[startup] Deployment config: mode=${deploymentMode} origins=${allowedOrigins.join(",")} hosts=${allowedHostnames.join(",")}`
+  );
+}

package/src/startup/env.ts

@@ -0,0 +1,17 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { config as loadDotenv } from "dotenv";
+
+export function loadApiEnv() {
+  const sourceDir = dirname(fileURLToPath(import.meta.url));
+  const repoRoot = resolve(sourceDir, "../../../../");
+  const candidates = [resolve(repoRoot, ".env.local"), resolve(repoRoot, ".env")];
+  for (const path of candidates) {
+    loadDotenv({ path, override: false, quiet: true });
+  }
+}
+
+export function normalizeOptionalDbPath(value: string | undefined) {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : undefined;
+}