bopodev-api 0.1.28 → 0.1.30

package/src/scripts/onboard-seed.ts

@@ -50,7 +50,16 @@ 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";
+type AgentProvider =
+  | "codex"
+  | "claude_code"
+  | "cursor"
+  | "gemini_cli"
+  | "opencode"
+  | "openai_api"
+  | "anthropic_api"
+  | "openclaw_gateway"
+  | "shell";
 const CEO_BOOTSTRAP_SUMMARY = "ceo bootstrap heartbeat";
 const STARTUP_PROJECT_NAME = "Leadership Setup";
 const CEO_STARTUP_TASK_TITLE = "Set up CEO operating files and hire founding engineer";
@@ -130,6 +139,8 @@ export async function ensureOnboardingSeed(input: {
           role: "CEO",
           roleKey: "ceo",
           title: "CEO",
+          capabilities:
+            "Company leadership: priorities, hiring, governance, and aligning agents to mission and budget.",
           name: "CEO",
           providerType: agentProvider,
           heartbeatCron: "*/5 * * * *",
@@ -316,18 +327,16 @@ async function ensureCeoStartupTask(
     `   - \`${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: ${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 \`${ceoTmpFolder}/\` (or OS temp via \`mktemp\`) and avoid chaining cleanup commands into critical task flow.`,
+    "3. Each heartbeat already includes your operating directory via `$BOPODEV_AGENT_OPERATING_DIR` and directs you to AGENTS.md and related files there when they exist.",
+    "   You do not need to save file paths into `bootstrapPrompt` for operating docs—reserve `bootstrapPrompt` only for optional extra standing instructions.",
+    `   - Prefer heredoc/stdin payloads (for example \`curl --data-binary @- <<'JSON' ... JSON\`) when calling APIs; if you must use payload files, store them in \`${ceoTmpFolder}/\` (or OS temp via \`mktemp\`).`,
     "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}'`",
+    "   - 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}'`",
     "5. Heartbeat-assigned issues are already claimed for the current run. Do not call a checkout endpoint; update status with `PUT /issues/:issueId` only.",
     "6. After your operating files are active, submit a hire request for a Founding Engineer via `POST /agents` using supported fields:",
     "   - `name`, `role`, `providerType`, `heartbeatCron`, `monthlyBudgetUsd`",
-    "   - optional `managerAgentId`, `bootstrapPrompt`, `runtimeConfig`, `canHireAgents`",
+    "   - optional `managerAgentId`, `bootstrapPrompt` (extra standing instructions only), `runtimeConfig`, `canHireAgents`",
     "   - `requestApproval: true` and `sourceIssueId`",
     "7. Do not use unsupported hire fields such as `adapterType`, `adapterConfig`, or `reportsTo`.",
     "",
@@ -401,6 +410,7 @@ function parseAgentProvider(value: unknown): AgentProvider | null {
     value === "opencode" ||
     value === "openai_api" ||
     value === "anthropic_api" ||
+    value === "openclaw_gateway" ||
     value === "shell"
   ) {
     return value;

package/src/server.ts

@@ -1,10 +1,5 @@
 import { createServer } from "node:http";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { config as loadDotenv } from "dotenv";
-import { bootstrapDatabase, listCompanies, resolveDefaultDbPath, sql } from "bopodev-db";
-import { checkRuntimeCommandHealth } from "bopodev-agent-sdk";
-import type { RuntimeCommandHealth } from "bopodev-agent-sdk";
+import { listCompanies } from "bopodev-db";
 import { createApp } from "./app";
 import { loadGovernanceRealtimeSnapshot } from "./realtime/governance";
 import { loadOfficeSpaceRealtimeSnapshot } from "./realtime/office-space";
@@ -12,7 +7,6 @@ import { loadHeartbeatRunsRealtimeSnapshot } from "./realtime/heartbeat-runs";
 import { loadAttentionRealtimeSnapshot } from "./realtime/attention";
 import { attachRealtimeHub } from "./realtime/hub";
 import {
-  isAuthenticatedMode,
   resolveAllowedHostnames,
   resolveAllowedOrigins,
   resolveDeploymentMode,
@@ -20,9 +14,18 @@ import {
 } from "./security/deployment-mode";
 import { ensureBuiltinPluginsRegistered } from "./services/plugin-runtime";
 import { ensureBuiltinTemplatesRegistered } from "./services/template-catalog";
-import { beginIssueCommentDispatchShutdown, waitForIssueCommentDispatchDrain } from "./services/comment-recipient-dispatch-service";
-import { beginHeartbeatQueueShutdown, waitForHeartbeatQueueDrain } from "./services/heartbeat-queue-service";
 import { createHeartbeatScheduler } from "./worker/scheduler";
+import { bootstrapDatabaseWithStartupLogging } from "./startup/database";
+import { validateDeploymentConfiguration } from "./startup/deployment-validation";
+import { loadApiEnv, normalizeOptionalDbPath } from "./startup/env";
+import {
+  buildGetRuntimeHealth,
+  hasCodexAgentsConfigured,
+  hasOpenCodeAgentsConfigured,
+  runStartupRuntimePreflights
+} from "./startup/runtime-health";
+import { resolveSchedulerCompanyId, shouldStartScheduler } from "./startup/scheduler-config";
+import { attachGracefulShutdownHandlers } from "./shutdown/graceful-shutdown";
 
 loadApiEnv();
 
@@ -33,33 +36,8 @@ async function main() {
   const publicBaseUrl = resolvePublicBaseUrl();
   validateDeploymentConfiguration(deploymentMode, allowedOrigins, allowedHostnames, publicBaseUrl);
   const dbPath = normalizeOptionalDbPath(process.env.BOPO_DB_PATH);
-  const usingExternalDatabase = Boolean(process.env.DATABASE_URL?.trim());
   const port = Number(process.env.PORT ?? 4020);
-  const effectiveDbPath = dbPath ?? resolveDefaultDbPath();
-  let db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"];
-  let dbClient: Awaited<ReturnType<typeof bootstrapDatabase>>["client"];
-  try {
-    const boot = await bootstrapDatabase(dbPath);
-    db = boot.db;
-    dbClient = boot.client;
-  } 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;
-  }
+  const { db, client: dbClient } = await bootstrapDatabaseWithStartupLogging(dbPath);
   const existingCompanies = await listCompanies(db);
   await ensureBuiltinPluginsRegistered(
     db,
@@ -79,54 +57,20 @@ async function main() {
   const openCodeHealthRequired =
     !skipOpenCodePreflight &&
     (process.env.BOPO_REQUIRE_OPENCODE_HEALTH === "1" || (await hasOpenCodeAgentsConfigured(db)));
-  const getRuntimeHealth = async () => {
-    const codex = codexHealthRequired
-      ? await checkRuntimeCommandHealth(codexCommand, {
-          timeoutMs: 5_000
-        })
-      : {
-          command: codexCommand,
-          available: skipCodexPreflight ? false : true,
-          exitCode: null,
-          elapsedMs: 0,
-          error: skipCodexPreflight
-            ? "Skipped by configuration: BOPO_SKIP_CODEX_PREFLIGHT=1."
-            : "Skipped: no Codex agents configured."
-        };
-    const opencode = openCodeHealthRequired
-      ? await checkRuntimeCommandHealth(openCodeCommand, {
-          timeoutMs: 5_000
-        })
-      : {
-          command: openCodeCommand,
-          available: skipOpenCodePreflight ? false : true,
-          exitCode: null,
-          elapsedMs: 0,
-          error: skipOpenCodePreflight
-            ? "Skipped by configuration: BOPO_SKIP_OPENCODE_PREFLIGHT=1."
-            : "Skipped: no OpenCode agents configured."
-        };
-    return {
-      codex,
-      opencode
-    };
-  };
-  if (codexHealthRequired) {
-    const startupCodexHealth = await checkRuntimeCommandHealth(codexCommand, {
-      timeoutMs: 5_000
-    });
-    if (!startupCodexHealth.available) {
-      emitCodexPreflightWarning(startupCodexHealth);
-    }
-  }
-  if (openCodeHealthRequired) {
-    const startupOpenCodeHealth = await checkRuntimeCommandHealth(openCodeCommand, {
-      timeoutMs: 5_000
-    });
-    if (!startupOpenCodeHealth.available) {
-      emitOpenCodePreflightWarning(startupOpenCodeHealth);
-    }
-  }
+  const getRuntimeHealth = buildGetRuntimeHealth({
+    codexCommand,
+    openCodeCommand,
+    skipCodexPreflight,
+    skipOpenCodePreflight,
+    codexHealthRequired,
+    openCodeHealthRequired
+  });
+  await runStartupRuntimePreflights({
+    codexHealthRequired,
+    openCodeHealthRequired,
+    codexCommand,
+    openCodeCommand
+  });
 
   const server = createServer();
   const realtimeHub = attachRealtimeHub(server, {
@@ -154,215 +98,12 @@ async function main() {
     console.log("[startup] Scheduler disabled for this instance (BOPO_SCHEDULER_ROLE is follower/off).");
   }
 
-  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"));
+  attachGracefulShutdownHandlers({
+    server,
+    realtimeHub,
+    dbClient,
+    scheduler
+  });
 }
 
 void main();
-
-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>)();
-}
-
-async function hasCodexAgentsConfigured(db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"]) {
-  const result = await db.execute(sql`
-    SELECT id
-    FROM agents
-    WHERE provider_type = 'codex'
-    LIMIT 1
-  `);
-  return result.length > 0;
-}
-
-async function hasOpenCodeAgentsConfigured(db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"]) {
-  const result = await db.execute(sql`
-    SELECT id
-    FROM agents
-    WHERE provider_type = 'opencode'
-    LIMIT 1
-  `);
-  return result.length > 0;
-}
-
-async function resolveSchedulerCompanyId(
-  db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"],
-  configuredCompanyId: string | null
-) {
-  if (configuredCompanyId) {
-    const configured = await db.execute(sql`
-      SELECT id
-      FROM companies
-      WHERE id = ${configuredCompanyId}
-      LIMIT 1
-    `);
-    if (configured.length > 0) {
-      return configuredCompanyId;
-    }
-    // eslint-disable-next-line no-console
-    console.warn(`[startup] BOPO_DEFAULT_COMPANY_ID='${configuredCompanyId}' was not found; using first available company.`);
-  }
-
-  const fallback = await db.execute(sql`
-    SELECT id
-    FROM companies
-    ORDER BY created_at ASC
-    LIMIT 1
-  `);
-  const id = fallback[0]?.id;
-  return typeof id === "string" && id.length > 0 ? id : null;
-}
-
-function emitCodexPreflightWarning(health: RuntimeCommandHealth) {
-  const red = process.stderr.isTTY ? "\x1b[31m" : "";
-  const yellow = process.stderr.isTTY ? "\x1b[33m" : "";
-  const reset = process.stderr.isTTY ? "\x1b[0m" : "";
-  const symbol = `${red}✖${reset}`;
-  process.stderr.write(
-    `${symbol} ${yellow}Codex preflight failed${reset}: command '${health.command}' is unavailable.\n`
-  );
-  process.stderr.write(`  Install Codex CLI or set BOPO_SKIP_CODEX_PREFLIGHT=1 for local dev.\n`);
-  if (process.env.BOPO_VERBOSE_STARTUP_WARNINGS === "1") {
-    process.stderr.write(`  Details: ${JSON.stringify(health)}\n`);
-  }
-}
-
-function emitOpenCodePreflightWarning(health: RuntimeCommandHealth) {
-  const red = process.stderr.isTTY ? "\x1b[31m" : "";
-  const yellow = process.stderr.isTTY ? "\x1b[33m" : "";
-  const reset = process.stderr.isTTY ? "\x1b[0m" : "";
-  const symbol = `${red}✖${reset}`;
-  process.stderr.write(
-    `${symbol} ${yellow}OpenCode preflight failed${reset}: command '${health.command}' is unavailable.\n`
-  );
-  process.stderr.write(`  Install OpenCode CLI or set BOPO_SKIP_OPENCODE_PREFLIGHT=1 for local dev.\n`);
-  if (process.env.BOPO_VERBOSE_STARTUP_WARNINGS === "1") {
-    process.stderr.write(`  Details: ${JSON.stringify(health)}\n`);
-  }
-}
-
-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, "../../../");
-  const candidates = [resolve(repoRoot, ".env.local"), resolve(repoRoot, ".env")];
-  for (const path of candidates) {
-    loadDotenv({ path, override: false, quiet: true });
-  }
-}
-
-function normalizeOptionalDbPath(value: string | undefined) {
-  const normalized = value?.trim();
-  return normalized && normalized.length > 0 ? normalized : undefined;
-}
-
-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")
-  );
-}

package/src/services/company-export-service.ts

@@ -0,0 +1,63 @@
+import type { BopoDb } from "bopodev-db";
+import { getCompany, listAgents, listGoals, listIssues, listProjects } from "bopodev-db";
+
+function serializeValue(value: unknown): unknown {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return serializeRow(value as Record<string, unknown>);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeValue(entry));
+  }
+  return value;
+}
+
+function serializeRow<T extends Record<string, unknown>>(row: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(row)) {
+    out[key] = serializeValue(val);
+  }
+  return out;
+}
+
+/** Strip agent fields that commonly hold secrets or session state for shareable exports. */
+function scrubAgentRow(agent: Record<string, unknown>) {
+  const base = serializeRow(agent);
+  return {
+    ...base,
+    runtimeEnvJson: "{}",
+    bootstrapPrompt: null,
+    stateBlob: "{}",
+    runtimeCommand: null,
+    runtimeArgsJson: "[]"
+  };
+}
+
+/**
+ * Portable company snapshot for backup, templates, or handoff (secrets and agent session state redacted).
+ */
+export async function buildCompanyPortabilityExport(db: BopoDb, companyId: string) {
+  const company = await getCompany(db, companyId);
+  if (!company) {
+    return null;
+  }
+
+  const [projects, goals, issues, agents] = await Promise.all([
+    listProjects(db, companyId),
+    listGoals(db, companyId),
+    listIssues(db, companyId),
+    listAgents(db, companyId)
+  ]);
+
+  return {
+    exportedAt: new Date().toISOString(),
+    formatVersion: 1,
+    company: serializeRow(company as unknown as Record<string, unknown>),
+    projects: projects.map((p) => serializeRow(p as unknown as Record<string, unknown>)),
+    goals: goals.map((g) => serializeRow(g as unknown as Record<string, unknown>)),
+    issues: issues.map((issue) => serializeRow(issue as unknown as Record<string, unknown>)),
+    agents: agents.map((agent) => scrubAgentRow(agent as unknown as Record<string, unknown>))
+  };
+}

package/src/services/governance-service.ts

@@ -60,19 +60,6 @@ const approvalGatedActions = new Set([
 const hireAgentPayloadSchema = AgentCreateRequestSchema.extend({
   sourceIssueId: z.string().min(1).optional(),
   sourceIssueIds: z.array(z.string().min(1)).default([]),
-  delegationIntent: z
-    .object({
-      intentType: z.literal("agent_hiring_request"),
-      requestedRole: z.string().nullable().optional(),
-      requestedName: z.string().nullable().optional(),
-      requestedManagerAgentId: z.string().nullable().optional(),
-      requestedProviderType: z
-        .enum(["claude_code", "codex", "cursor", "opencode", "gemini_cli", "openai_api", "anthropic_api", "http", "shell"])
-        .nullable()
-        .optional(),
-      requestedRuntimeModel: z.string().nullable().optional()
-    })
-    .optional(),
   runtimeCommand: z.string().optional(),
   runtimeArgs: z.array(z.string()).optional(),
   runtimeCwd: z.string().optional(),
@@ -94,6 +81,7 @@ const hireAgentPayloadSchema = AgentCreateRequestSchema.extend({
 const activateGoalPayloadSchema = z.object({
   projectId: z.string().optional(),
   parentGoalId: z.string().optional(),
+  ownerAgentId: z.string().optional(),
   level: z.enum(["company", "project", "agent"]),
   title: z.string().min(1),
   description: z.string().optional()
@@ -309,6 +297,7 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
       role: resolveAgentRoleText(parsed.data.role, parsed.data.roleKey, parsed.data.title),
       roleKey: normalizeRoleKey(parsed.data.roleKey),
       title: normalizeTitle(parsed.data.title),
+      capabilities: normalizeCapabilities(parsed.data.capabilities),
       name: parsed.data.name,
       providerType: parsed.data.providerType,
       heartbeatCron: parsed.data.heartbeatCron,
@@ -372,6 +361,7 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
       companyId,
       projectId: parsed.data.projectId,
       parentGoalId: parsed.data.parentGoalId,
+      ownerAgentId: parsed.data.ownerAgentId,
       level: parsed.data.level,
       title: parsed.data.title,
       description: parsed.data.description
@@ -737,6 +727,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,
@@ -784,7 +779,8 @@ function buildAgentStartupTaskBody(companyId: string, agentId: string) {
     `   - \`${agentOperatingFolder}/HEARTBEAT.md\``,
     `   - \`${agentOperatingFolder}/SOUL.md\``,
     `   - \`${agentOperatingFolder}/TOOLS.md\``,
-    `3. Update your own agent runtime config via \`PUT /agents/:agentId\` and set \`runtimeConfig.bootstrapPrompt\` to reference \`${agentOperatingFolder}/AGENTS.md\` as your primary guide.`,
+    "3. Each heartbeat already includes your operating directory via `$BOPODEV_AGENT_OPERATING_DIR` and directs you to AGENTS.md and related files there when they exist.",
+    "   You do not need to save file paths into `bootstrapPrompt` for operating docs—use `PUT /agents/:agentId` `bootstrapPrompt` only for optional extra standing instructions.",
     "4. Post an issue comment summarizing completed setup artifacts.",
     "",
     "Safety checks:",

package/src/services/heartbeat-service/active-runs.ts

@@ -0,0 +1,15 @@
+import type { ActiveHeartbeatRun } from "./types";
+
+const activeHeartbeatRuns = new Map<string, ActiveHeartbeatRun>();
+
+export function registerActiveHeartbeatRun(runId: string, run: ActiveHeartbeatRun) {
+  activeHeartbeatRuns.set(runId, run);
+}
+
+export function unregisterActiveHeartbeatRun(runId: string) {
+  activeHeartbeatRuns.delete(runId);
+}
+
+export function getActiveHeartbeatRun(runId: string) {
+  return activeHeartbeatRuns.get(runId);
+}

package/src/services/heartbeat-service/budget-override.ts

@@ -0,0 +1,46 @@
+import { and, eq, inArray, approvalRequests, issues } from "bopodev-db";
+import type { BopoDb } from "bopodev-db";
+
+export async function findPendingProjectBudgetOverrideBlocksForAgent(
+  db: BopoDb,
+  companyId: string,
+  agentId: string
+) {
+  const assignedRows = await db
+    .select({ projectId: issues.projectId })
+    .from(issues)
+    .where(
+      and(
+        eq(issues.companyId, companyId),
+        eq(issues.assigneeAgentId, agentId),
+        inArray(issues.status, ["todo", "in_progress"])
+      )
+    );
+  const assignedProjectIds = new Set(assignedRows.map((row) => row.projectId));
+  if (assignedProjectIds.size === 0) {
+    return [] as string[];
+  }
+  const pendingOverrides = await db
+    .select({ payloadJson: approvalRequests.payloadJson })
+    .from(approvalRequests)
+    .where(
+      and(
+        eq(approvalRequests.companyId, companyId),
+        eq(approvalRequests.action, "override_budget"),
+        eq(approvalRequests.status, "pending")
+      )
+    );
+  const blockedProjectIds = new Set<string>();
+  for (const approval of pendingOverrides) {
+    try {
+      const payload = JSON.parse(approval.payloadJson) as Record<string, unknown>;
+      const projectId = typeof payload.projectId === "string" ? payload.projectId.trim() : "";
+      if (projectId && assignedProjectIds.has(projectId)) {
+        blockedProjectIds.add(projectId);
+      }
+    } catch {
+      // Ignore malformed payloads to keep enforcement resilient.
+    }
+  }
+  return Array.from(blockedProjectIds);
+}

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

@@ -0,0 +1,61 @@
+import { and, eq, inArray, issues, sql } from "bopodev-db";
+import type { BopoDb } from "bopodev-db";
+
+export async function claimIssuesForAgent(
+  db: BopoDb,
+  companyId: string,
+  agentId: string,
+  heartbeatRunId: string,
+  maxItems = 5
+) {
+  const result = await db.execute(sql`
+    WITH candidate AS (
+      SELECT id
+      FROM issues
+      WHERE company_id = ${companyId}
+        AND assignee_agent_id = ${agentId}
+        AND status IN ('todo', 'in_progress')
+        AND is_claimed = false
+      ORDER BY
+        CASE priority
+          WHEN 'urgent' THEN 0
+          WHEN 'high' THEN 1
+          WHEN 'medium' THEN 2
+          WHEN 'low' THEN 3
+          ELSE 4
+        END ASC,
+        updated_at ASC
+      LIMIT ${maxItems}
+      FOR UPDATE SKIP LOCKED
+    )
+    UPDATE issues i
+    SET is_claimed = true,
+        claimed_by_heartbeat_run_id = ${heartbeatRunId},
+        updated_at = CURRENT_TIMESTAMP
+    FROM candidate c
+    WHERE i.id = c.id
+    RETURNING i.id, i.project_id, i.parent_issue_id, i.title, i.body, i.status, i.priority, i.labels_json, i.tags_json;
+  `);
+
+  return result as unknown as Array<{
+    id: string;
+    project_id: string;
+    parent_issue_id: string | null;
+    title: string;
+    body: string | null;
+    status: string;
+    priority: string;
+    labels_json: string;
+    tags_json: string;
+  }>;
+}
+
+export async function releaseClaimedIssues(db: BopoDb, companyId: string, issueIds: string[]) {
+  if (issueIds.length === 0) {
+    return;
+  }
+  await db
+    .update(issues)
+    .set({ isClaimed: false, claimedByHeartbeatRunId: null, updatedAt: new Date() })
+    .where(and(eq(issues.companyId, companyId), inArray(issues.id, issueIds)));
+}