bopodev-api 0.1.14 → 0.1.16

package/src/scripts/onboard-seed.ts

@@ -1,23 +1,38 @@
 import { pathToFileURL } from "node:url";
 import { mkdir } from "node:fs/promises";
+import { TemplateManifestDefault, TemplateManifestSchema } from "bopodev-contracts";
 import { getAdapterModels } from "bopodev-agent-sdk";
 import {
   bootstrapDatabase,
+  createProjectWorkspace,
   createAgent,
+  getCurrentTemplateVersion,
+  getTemplate,
+  getTemplateBySlug,
   createCompany,
   createIssue,
   createProject,
   listAgents,
   listCompanies,
   listIssues,
+  listProjectWorkspaces,
   listProjects,
+  updateProjectWorkspace,
   updateIssue,
   updateAgent,
   updateCompany
 } from "bopodev-db";
 import { normalizeRuntimeConfig, runtimeConfigToDb, runtimeConfigToStateBlobPatch } from "../lib/agent-config";
+import {
+  normalizeAbsolutePath,
+  normalizeCompanyWorkspacePath,
+  resolveAgentFallbackWorkspacePath,
+  resolveProjectWorkspacePath
+} from "../lib/instance-paths";
 import { resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
 import { ensureCompanyModelPricingDefaults } from "../services/model-pricing";
+import { applyTemplateManifest } from "../services/template-apply-service";
+import { ensureCompanyBuiltinTemplateDefaults } from "../services/template-catalog";
 
 export interface OnboardSeedSummary {
   companyId: string;
@@ -25,12 +40,17 @@ export interface OnboardSeedSummary {
   companyCreated: boolean;
   ceoCreated: boolean;
   ceoProviderType: AgentProvider;
+  ceoRuntimeModel: string | null;
   ceoMigrated: boolean;
+  templateApplied: boolean;
+  templateId: string | null;
 }
 
 const DEFAULT_COMPANY_NAME_ENV = "BOPO_DEFAULT_COMPANY_NAME";
 const DEFAULT_COMPANY_ID_ENV = "BOPO_DEFAULT_COMPANY_ID";
 const DEFAULT_AGENT_PROVIDER_ENV = "BOPO_DEFAULT_AGENT_PROVIDER";
+const DEFAULT_AGENT_MODEL_ENV = "BOPO_DEFAULT_AGENT_MODEL";
+const DEFAULT_TEMPLATE_ENV = "BOPO_DEFAULT_TEMPLATE_ID";
 type AgentProvider = "codex" | "claude_code" | "cursor" | "gemini_cli" | "opencode" | "openai_api" | "anthropic_api" | "shell";
 const CEO_BOOTSTRAP_SUMMARY = "ceo bootstrap heartbeat";
 const STARTUP_PROJECT_NAME = "Leadership Setup";
@@ -42,12 +62,15 @@ export async function ensureOnboardingSeed(input: {
   companyName: string;
   companyId?: string;
   agentProvider?: AgentProvider;
+  agentModel?: string;
+  templateId?: string;
 }): Promise<OnboardSeedSummary> {
   const companyName = input.companyName.trim();
   if (companyName.length === 0) {
     throw new Error("BOPO_DEFAULT_COMPANY_NAME is required for onboarding seed.");
   }
   const agentProvider = parseAgentProvider(input.agentProvider) ?? "shell";
+  const requestedAgentModel = input.agentModel?.trim() || undefined;
 
   const { db, client } = await bootstrapDatabase(input.dbPath);
 
@@ -73,14 +96,16 @@ export async function ensureOnboardingSeed(input: {
 
     const companyId = companyRow.id;
     const resolvedCompanyName = companyRow.name;
+    await ensureCompanyBuiltinTemplateDefaults(db, companyId);
     const defaultRuntimeCwd = await resolveDefaultRuntimeCwdForCompany(db, companyId);
-    await mkdir(defaultRuntimeCwd, { recursive: true });
+    await mkdir(normalizeCompanyWorkspacePath(companyId, defaultRuntimeCwd), { recursive: true });
     const seedRuntimeEnv = resolveSeedRuntimeEnv(agentProvider);
     const defaultRuntimeConfig = normalizeRuntimeConfig({
       defaultRuntimeCwd,
       runtimeConfig: {
         runtimeEnv: seedRuntimeEnv,
         runtimeModel: await resolveSeedRuntimeModel(agentProvider, {
+          requestedModel: requestedAgentModel,
           defaultRuntimeCwd,
           runtimeEnv: seedRuntimeEnv
         })
@@ -91,6 +116,7 @@ export async function ensureOnboardingSeed(input: {
     let ceoCreated = false;
     let ceoMigrated = false;
     let ceoProviderType: AgentProvider = parseAgentProvider(existingCeo?.providerType) ?? agentProvider;
+    let ceoRuntimeModel = existingCeo?.runtimeModel ?? null;
 
     let ceoId = existingCeo?.id ?? null;
 
@@ -109,6 +135,7 @@ export async function ensureOnboardingSeed(input: {
       ceoId = ceo.id;
       ceoCreated = true;
       ceoProviderType = agentProvider;
+      ceoRuntimeModel = ceo.runtimeModel ?? defaultRuntimeConfig.runtimeModel ?? null;
     } else if (isBootstrapCeoRuntime(existingCeo.providerType, existingCeo.stateBlob)) {
       const nextState = {
         ...stripRuntimeFromState(existingCeo.stateBlob),
@@ -124,8 +151,10 @@ export async function ensureOnboardingSeed(input: {
       ceoMigrated = true;
       ceoProviderType = agentProvider;
       ceoId = existingCeo.id;
+      ceoRuntimeModel = defaultRuntimeConfig.runtimeModel ?? null;
     } else {
       ceoId = existingCeo.id;
+      ceoRuntimeModel = existingCeo.runtimeModel ?? null;
     }
 
     if (ceoId) {
@@ -136,6 +165,39 @@ export async function ensureOnboardingSeed(input: {
         ceoId
       });
     }
+    let templateApplied = false;
+    let appliedTemplateId: string | null = null;
+    if (input.templateId?.trim()) {
+      const requestedTemplateId = input.templateId.trim();
+      const template =
+        (await getTemplate(db, companyId, requestedTemplateId)) ??
+        (await getTemplateBySlug(db, companyId, requestedTemplateId));
+      if (template) {
+        const templateVersion = await getCurrentTemplateVersion(db, companyId, template.id);
+        if (templateVersion) {
+          let manifest: Record<string, unknown> = {};
+          try {
+            manifest = JSON.parse(templateVersion.manifestJson) as Record<string, unknown>;
+          } catch {
+            manifest = {};
+          }
+          const parsedManifest = TemplateManifestSchema.safeParse(manifest);
+          const normalizedManifest = parsedManifest.success
+            ? parsedManifest.data
+            : TemplateManifestSchema.parse(TemplateManifestDefault);
+          const applied = await applyTemplateManifest(db, {
+            companyId,
+            templateId: template.id,
+            templateVersion: templateVersion.version,
+            templateVersionId: templateVersion.id,
+            manifest: normalizedManifest,
+            variables: {}
+          });
+          templateApplied = applied.applied;
+          appliedTemplateId = template.id;
+        }
+      }
+    }
     await ensureCompanyModelPricingDefaults(db, companyId);
 
     return {
@@ -144,7 +206,10 @@ export async function ensureOnboardingSeed(input: {
       companyCreated,
       ceoCreated,
       ceoProviderType,
-      ceoMigrated
+      ceoRuntimeModel,
+      ceoMigrated,
+      templateApplied,
+      templateId: appliedTemplateId
     };
   } finally {
     const maybeClose = (client as { close?: () => Promise<void> }).close;
@@ -158,6 +223,7 @@ async function ensureStartupProject(db: Awaited<ReturnType<typeof bootstrapDatab
   const projects = await listProjects(db, companyId);
   const existing = projects.find((project) => project.name === STARTUP_PROJECT_NAME);
   if (existing) {
+    await ensureProjectPrimaryWorkspace(db, companyId, existing.id, STARTUP_PROJECT_NAME);
     return existing.id;
   }
   const created = await createProject(db, {
@@ -165,9 +231,54 @@ async function ensureStartupProject(db: Awaited<ReturnType<typeof bootstrapDatab
     name: STARTUP_PROJECT_NAME,
     description: "Initial leadership onboarding and operating setup."
   });
+  if (!created) {
+    throw new Error("Failed to create startup project.");
+  }
+  await ensureProjectPrimaryWorkspace(db, companyId, created.id, STARTUP_PROJECT_NAME);
   return created.id;
 }
 
+async function ensureProjectPrimaryWorkspace(
+  db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"],
+  companyId: string,
+  projectId: string,
+  projectName: string
+) {
+  const existingWorkspaces = await listProjectWorkspaces(db, companyId, projectId);
+  const existingPrimary = existingWorkspaces.find((workspace) => workspace.isPrimary);
+  if (existingPrimary) {
+    if (existingPrimary.cwd) {
+      await mkdir(normalizeCompanyWorkspacePath(companyId, existingPrimary.cwd), { recursive: true });
+    }
+    return existingPrimary;
+  }
+  const defaultWorkspaceCwd = resolveProjectWorkspacePath(companyId, projectId);
+  await mkdir(defaultWorkspaceCwd, { recursive: true });
+  const fallbackWorkspace = existingWorkspaces[0];
+  if (fallbackWorkspace) {
+    const normalizedCwd = fallbackWorkspace.cwd?.trim()
+      ? normalizeCompanyWorkspacePath(companyId, fallbackWorkspace.cwd)
+      : defaultWorkspaceCwd;
+    if (normalizedCwd) {
+      await mkdir(normalizedCwd, { recursive: true });
+    }
+    return updateProjectWorkspace(db, {
+      companyId,
+      projectId,
+      id: fallbackWorkspace.id,
+      cwd: normalizedCwd,
+      isPrimary: true
+    });
+  }
+  return createProjectWorkspace(db, {
+    companyId,
+    projectId,
+    name: projectName,
+    cwd: defaultWorkspaceCwd,
+    isPrimary: true
+  });
+}
+
 async function ensureCeoStartupTask(
   db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"],
   input: { companyId: string; projectId: string; ceoId: string }
@@ -180,22 +291,25 @@ async function ensureCeoStartupTask(
       typeof issue.body === "string" &&
       issue.body.includes(CEO_STARTUP_TASK_MARKER)
   );
+  const ceoWorkspaceRoot = resolveAgentFallbackWorkspacePath(input.companyId, input.ceoId);
+  const ceoOperatingFolder = `${ceoWorkspaceRoot}/operating`;
+  const ceoTmpFolder = `${ceoWorkspaceRoot}/tmp`;
   const body = [
     CEO_STARTUP_TASK_MARKER,
     "",
     "Stand up your leadership operating baseline before taking on additional delivery work.",
     "",
-    `1. Create the folder \`agents/${input.ceoId}/\` in the repository workspace.`,
+    `1. Create your operating folder at \`${ceoOperatingFolder}/\` (system path, outside project workspaces).`,
     "2. Author these files with your own voice and responsibilities:",
-    `   - \`agents/${input.ceoId}/AGENTS.md\``,
-    `   - \`agents/${input.ceoId}/HEARTBEAT.md\``,
-    `   - \`agents/${input.ceoId}/SOUL.md\``,
-    `   - \`agents/${input.ceoId}/TOOLS.md\``,
+    `   - \`${ceoOperatingFolder}/AGENTS.md\``,
+    `   - \`${ceoOperatingFolder}/HEARTBEAT.md\``,
+    `   - \`${ceoOperatingFolder}/SOUL.md\``,
+    `   - \`${ceoOperatingFolder}/TOOLS.md\``,
     "3. Save your operating-file reference on your own agent record via `PUT /agents/:agentId`.",
-    `   - Supported simple body: \`{ "bootstrapPrompt": "Primary operating reference: agents/${input.ceoId}/AGENTS.md ..." }\``,
+    `   - Supported simple body: \`{ "bootstrapPrompt": "Primary operating reference: ${ceoOperatingFolder}/AGENTS.md ..." }\``,
     "   - If using `runtimeConfig`, only `runtimeConfig.bootstrapPrompt` is supported there.",
     "   - Prefer heredoc/stdin payloads (for example `curl --data-binary @- <<'JSON' ... JSON`) to avoid temp-file cleanup failures under runtime policy.",
-    `   - If you must use payload files, store them in \`agents/${input.ceoId}/tmp/\` (or OS temp via \`mktemp\`) and avoid chaining cleanup commands into critical task flow.`,
+    `   - If you must use payload files, store them in \`${ceoTmpFolder}/\` (or OS temp via \`mktemp\`) and avoid chaining cleanup commands into critical task flow.`,
     "4. To inspect your own agent record, use `GET /agents` and filter by your agent id. Do not call `GET /agents/:agentId`.",
     "   - `GET /agents` uses envelope shape `{ \"ok\": true, \"data\": [...] }`; treat any other shape as failure.",
     "   - Deterministic filter: `jq -er --arg id \"$BOPODEV_AGENT_ID\" '.data | if type==\"array\" then . else error(\"invalid_agents_payload\") end | map(select((.id? // \"\") == $id))[0] | {id,name,role,bootstrapPrompt}'`",
@@ -207,6 +321,7 @@ async function ensureCeoStartupTask(
     "7. Do not use unsupported hire fields such as `adapterType`, `adapterConfig`, or `reportsTo`.",
     "",
     "Safety checks before requesting hire:",
+    "- Do not write operating/system files under any project workspace folder.",
     "- Do not request duplicates if a Founding Engineer already exists.",
     "- Do not request duplicates if a pending approval for the same role is already open.",
     "- For control-plane calls, prefer direct header env vars (`BOPODEV_COMPANY_ID`, `BOPODEV_ACTOR_TYPE`, `BOPODEV_ACTOR_ID`, `BOPODEV_ACTOR_COMPANIES`, `BOPODEV_ACTOR_PERMISSIONS`) instead of parsing `BOPODEV_REQUEST_HEADERS_JSON`.",
@@ -242,11 +357,16 @@ async function main() {
   const companyName = process.env[DEFAULT_COMPANY_NAME_ENV]?.trim() ?? "";
   const companyId = process.env[DEFAULT_COMPANY_ID_ENV]?.trim() || undefined;
   const agentProvider = parseAgentProvider(process.env[DEFAULT_AGENT_PROVIDER_ENV]) ?? undefined;
+  const agentModel = process.env[DEFAULT_AGENT_MODEL_ENV]?.trim() || undefined;
+  const templateId = process.env[DEFAULT_TEMPLATE_ENV]?.trim() || undefined;
+  const dbPath = normalizeOptionalDbPath(process.env.BOPO_DB_PATH);
   const result = await ensureOnboardingSeed({
-    dbPath: process.env.BOPO_DB_PATH,
+    dbPath,
     companyName,
     companyId,
-    agentProvider
+    agentProvider,
+    agentModel,
+    templateId
   });
   // eslint-disable-next-line no-console
   console.log(JSON.stringify(result));
@@ -256,6 +376,11 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
   void main();
 }
 
+function normalizeOptionalDbPath(value: string | undefined) {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalizeAbsolutePath(normalized, { requireAbsoluteInput: true }) : undefined;
+}
+
 function parseAgentProvider(value: unknown): AgentProvider | null {
   if (
     value === "codex" ||
@@ -296,8 +421,11 @@ function resolveSeedRuntimeEnv(agentProvider: AgentProvider): Record<string, str
 
 async function resolveSeedRuntimeModel(
   agentProvider: AgentProvider,
-  input: { defaultRuntimeCwd: string; runtimeEnv: Record<string, string> }
+  input: { requestedModel?: string; defaultRuntimeCwd: string; runtimeEnv: Record<string, string> }
 ): Promise<string | undefined> {
+  if (input.requestedModel) {
+    return input.requestedModel;
+  }
   if (agentProvider !== "opencode") {
     return undefined;
   }

package/src/security/actor-token.ts

@@ -0,0 +1,133 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+type ActorType = "board" | "member" | "agent";
+
+export type ActorTokenPayload = {
+  v: 1;
+  iat: number;
+  exp: number;
+  actorType: ActorType;
+  actorId: string;
+  actorCompanies: string[] | null;
+  actorPermissions: string[];
+};
+
+export type ActorIdentity = {
+  type: ActorType;
+  id: string;
+  companyIds: string[] | null;
+  permissions: string[];
+};
+
+export function issueActorToken(
+  input: {
+    actorType: ActorType;
+    actorId: string;
+    actorCompanies: string[] | null;
+    actorPermissions: string[];
+    ttlSec?: number;
+  },
+  secret: string
+) {
+  const nowSec = Math.floor(Date.now() / 1000);
+  const ttlSec = Math.max(60, Math.min(86_400, input.ttlSec ?? 3_600));
+  const payload: ActorTokenPayload = {
+    v: 1,
+    iat: nowSec,
+    exp: nowSec + ttlSec,
+    actorType: input.actorType,
+    actorId: input.actorId.trim(),
+    actorCompanies: input.actorType === "board" ? null : input.actorCompanies ?? [],
+    actorPermissions: dedupe(input.actorPermissions)
+  };
+  const encodedPayload = encodeBase64Url(JSON.stringify(payload));
+  const signature = sign(encodedPayload, secret);
+  return `${encodedPayload}.${signature}`;
+}
+
+export function verifyActorToken(token: string | undefined | null, secret: string): ActorIdentity | null {
+  const trimmed = token?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const [encodedPayload, encodedSignature] = trimmed.split(".");
+  if (!encodedPayload || !encodedSignature) {
+    return null;
+  }
+  const expectedSignature = sign(encodedPayload, secret);
+  if (!safeStringEqual(expectedSignature, encodedSignature)) {
+    return null;
+  }
+  const decoded = decodeBase64Url(encodedPayload);
+  if (!decoded) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") {
+    return null;
+  }
+  const payload = parsed as Partial<ActorTokenPayload>;
+  if (payload.v !== 1 || typeof payload.exp !== "number" || typeof payload.iat !== "number") {
+    return null;
+  }
+  const nowSec = Math.floor(Date.now() / 1000);
+  if (payload.exp < nowSec) {
+    return null;
+  }
+  if (payload.actorType !== "board" && payload.actorType !== "member" && payload.actorType !== "agent") {
+    return null;
+  }
+  if (typeof payload.actorId !== "string" || payload.actorId.trim().length === 0) {
+    return null;
+  }
+  const companyIds =
+    payload.actorType === "board"
+      ? null
+      : Array.isArray(payload.actorCompanies)
+        ? payload.actorCompanies.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+        : [];
+  const permissions = Array.isArray(payload.actorPermissions)
+    ? payload.actorPermissions.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+  return {
+    type: payload.actorType,
+    id: payload.actorId.trim(),
+    companyIds,
+    permissions: dedupe(permissions)
+  };
+}
+
+function sign(encodedPayload: string, secret: string) {
+  const digest = createHmac("sha256", secret).update(encodedPayload).digest("base64url");
+  return digest;
+}
+
+function encodeBase64Url(value: string) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function decodeBase64Url(value: string) {
+  try {
+    return Buffer.from(value, "base64url").toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function safeStringEqual(left: string, right: string) {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  if (leftBuffer.length !== rightBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+function dedupe(values: string[]) {
+  return Array.from(new Set(values.map((entry) => entry.trim()).filter(Boolean)));
+}

package/src/security/deployment-mode.ts

@@ -0,0 +1,73 @@
+import { URL } from "node:url";
+
+export type DeploymentMode = "local" | "authenticated_private" | "authenticated_public";
+
+const VALID_MODES = new Set<DeploymentMode>(["local", "authenticated_private", "authenticated_public"]);
+
+export function resolveDeploymentMode(raw = process.env.BOPO_DEPLOYMENT_MODE): DeploymentMode {
+  const normalized = raw?.trim() ?? "";
+  if (!normalized) {
+    return "local";
+  }
+  if (VALID_MODES.has(normalized as DeploymentMode)) {
+    return normalized as DeploymentMode;
+  }
+  throw new Error(
+    `Invalid BOPO_DEPLOYMENT_MODE '${normalized}'. Expected one of: local, authenticated_private, authenticated_public.`
+  );
+}
+
+export function isAuthenticatedMode(mode: DeploymentMode) {
+  return mode === "authenticated_private" || mode === "authenticated_public";
+}
+
+export function resolveAllowedOrigins(mode: DeploymentMode, raw = process.env.BOPO_ALLOWED_ORIGINS) {
+  if (mode === "local") {
+    return ["http://localhost:4010", "http://127.0.0.1:4010"] as string[];
+  }
+  const parsed = parseCommaList(raw);
+  if (parsed.length === 0) {
+    throw new Error(
+      `BOPO_ALLOWED_ORIGINS is required in ${mode} mode. Example: https://bopo.example.com,https://admin.example.com`
+    );
+  }
+  return parsed;
+}
+
+export function resolvePublicBaseUrl(raw = process.env.BOPO_PUBLIC_BASE_URL) {
+  const value = raw?.trim() ?? "";
+  if (!value) {
+    return null;
+  }
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`BOPO_PUBLIC_BASE_URL must be a valid URL. Received: '${value}'.`);
+  }
+}
+
+export function resolveAllowedHostnames(mode: DeploymentMode, raw = process.env.BOPO_ALLOWED_HOSTNAMES) {
+  const hostnames = new Set(parseCommaList(raw));
+  const publicUrl = resolvePublicBaseUrl();
+  if (publicUrl?.hostname) {
+    hostnames.add(publicUrl.hostname);
+  }
+  if (mode === "local" && hostnames.size === 0) {
+    hostnames.add("localhost");
+    hostnames.add("127.0.0.1");
+  }
+  if (isAuthenticatedMode(mode) && hostnames.size === 0) {
+    throw new Error(`BOPO_ALLOWED_HOSTNAMES is required in ${mode} mode.`);
+  }
+  return Array.from(hostnames);
+}
+
+export function parseCommaList(value: string | undefined | null) {
+  if (!value) {
+    return [];
+  }
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}

package/src/server.ts

@@ -11,13 +11,26 @@ import { loadGovernanceRealtimeSnapshot } from "./realtime/governance";
 import { loadOfficeSpaceRealtimeSnapshot } from "./realtime/office-space";
 import { loadHeartbeatRunsRealtimeSnapshot } from "./realtime/heartbeat-runs";
 import { attachRealtimeHub } from "./realtime/hub";
+import {
+  isAuthenticatedMode,
+  resolveAllowedHostnames,
+  resolveAllowedOrigins,
+  resolveDeploymentMode,
+  resolvePublicBaseUrl
+} from "./security/deployment-mode";
 import { ensureBuiltinPluginsRegistered } from "./services/plugin-runtime";
+import { ensureBuiltinTemplatesRegistered } from "./services/template-catalog";
 import { createHeartbeatScheduler } from "./worker/scheduler";
 
 loadApiEnv();
 
 async function main() {
-  const dbPath = process.env.BOPO_DB_PATH;
+  const deploymentMode = resolveDeploymentMode();
+  const allowedOrigins = resolveAllowedOrigins(deploymentMode);
+  const allowedHostnames = resolveAllowedHostnames(deploymentMode);
+  const publicBaseUrl = resolvePublicBaseUrl();
+  validateDeploymentConfiguration(deploymentMode, allowedOrigins, allowedHostnames, publicBaseUrl);
+  const dbPath = normalizeOptionalDbPath(process.env.BOPO_DB_PATH);
   const port = Number(process.env.PORT ?? 4020);
   const { db } = await bootstrapDatabase(dbPath);
   const existingCompanies = await listCompanies(db);
@@ -25,6 +38,10 @@ async function main() {
     db,
     existingCompanies.map((company) => company.id)
   );
+  await ensureBuiltinTemplatesRegistered(
+    db,
+    existingCompanies.map((company) => company.id)
+  );
   const codexCommand = process.env.BOPO_CODEX_COMMAND ?? "codex";
   const openCodeCommand = process.env.BOPO_OPENCODE_COMMAND ?? "opencode";
   const skipCodexPreflight = process.env.BOPO_SKIP_CODEX_PREFLIGHT === "1";
@@ -92,17 +109,20 @@ async function main() {
       "heartbeat-runs": (companyId) => loadHeartbeatRunsRealtimeSnapshot(db, companyId)
     }
   });
-  const app = createApp({ db, getRuntimeHealth, realtimeHub });
+  const app = createApp({ db, deploymentMode, allowedOrigins, getRuntimeHealth, realtimeHub });
   server.on("request", app);
   server.listen(port, () => {
     // eslint-disable-next-line no-console
-    console.log(`BopoDev API running on http://localhost:${port}`);
+    console.log(`BopoDev API running in ${deploymentMode} mode on port ${port}`);
   });
 
   const defaultCompanyId = process.env.BOPO_DEFAULT_COMPANY_ID;
   const schedulerCompanyId = await resolveSchedulerCompanyId(db, defaultCompanyId ?? null);
-  if (schedulerCompanyId) {
+  if (schedulerCompanyId && shouldStartScheduler()) {
     createHeartbeatScheduler(db, schedulerCompanyId, realtimeHub);
+  } else if (schedulerCompanyId) {
+    // eslint-disable-next-line no-console
+    console.log("[startup] Scheduler disabled for this instance (BOPO_SCHEDULER_ROLE is follower/off).");
   }
 }
 
@@ -184,6 +204,49 @@ function emitOpenCodePreflightWarning(health: RuntimeCommandHealth) {
   }
 }
 
+function validateDeploymentConfiguration(
+  deploymentMode: ReturnType<typeof resolveDeploymentMode>,
+  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(",")}`
+  );
+}
+
+function shouldStartScheduler() {
+  const rawRole = (process.env.BOPO_SCHEDULER_ROLE ?? "auto").trim().toLowerCase();
+  if (rawRole === "off" || rawRole === "follower") {
+    return false;
+  }
+  if (rawRole === "leader" || rawRole === "auto") {
+    return true;
+  }
+  throw new Error(`Invalid BOPO_SCHEDULER_ROLE '${rawRole}'. Expected one of: auto, leader, follower, off.`);
+}
+
 function loadApiEnv() {
   const sourceDir = dirname(fileURLToPath(import.meta.url));
   const repoRoot = resolve(sourceDir, "../../../");
@@ -192,3 +255,8 @@ function loadApiEnv() {
     loadDotenv({ path, override: false, quiet: true });
   }
 }
+
+function normalizeOptionalDbPath(value: string | undefined) {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : undefined;
+}