@bugmole/cli 0.4.0

package/src/registry-worker/repo-triggers.ts

@@ -0,0 +1,20 @@
+// Shared by GitHub and GitLab checks: turning a preview-URL template into a
+// real URL for a given commit, safely.
+
+/** Fills {number}, {sha}, {short_sha} and {branch} into a preview URL template. */
+export function previewUrl(template: string, values: { number?: number; sha: string; branch?: string }): string | null {
+  const branch = (values.branch ?? "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (template.includes("{number}") && values.number === undefined) return null;
+  if (template.includes("{branch}") && !branch) return null;
+  const filled = template
+    .replaceAll("{number}", String(values.number ?? ""))
+    .replaceAll("{sha}", values.sha)
+    .replaceAll("{short_sha}", values.sha.slice(0, 7))
+    .replaceAll("{branch}", branch);
+  try {
+    const url = new URL(filled);
+    return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}

package/src/registry-worker/routes/index.ts

@@ -0,0 +1,74 @@
+// Router for the registry features added after the original index.ts routes.
+// Each feature module exposes `route(ctx)` and returns null when the request
+// isn't one of its own, so index.ts stays a thin dispatcher.
+import type { Env, Principal } from "../core.js";
+
+export type RouteContext = {
+  request: Request;
+  env: Env;
+  url: URL;
+  ctx: ExecutionContext;
+};
+
+export type AuthedRouteContext = RouteContext & { principal: Principal };
+
+type PublicRoute = (context: RouteContext) => Promise<Response | null>;
+type AuthedRoute = (context: AuthedRouteContext) => Promise<Response | null>;
+
+const publicRoutes: PublicRoute[] = [];
+const authedRoutes: AuthedRoute[] = [];
+
+export function registerPublicRoutes(route: PublicRoute): void {
+  publicRoutes.push(route);
+}
+
+export function registerRoutes(route: AuthedRoute): void {
+  authedRoutes.push(route);
+}
+
+export async function handlePublicRoutes(request: Request, env: Env, url: URL, ctx: ExecutionContext): Promise<Response | null> {
+  for (const route of publicRoutes) {
+    const result = await route({ request, env, url, ctx });
+    if (result) return result;
+  }
+  return null;
+}
+
+export async function handleExtendedRoutes(
+  request: Request,
+  env: Env,
+  principal: Principal,
+  url: URL,
+  ctx: ExecutionContext,
+): Promise<Response | null> {
+  for (const route of authedRoutes) {
+    const result = await route({ request, env, principal, url, ctx });
+    if (result) return result;
+  }
+  return null;
+}
+
+/** For callers without an ExecutionContext: background work simply runs inline. */
+export function detachedContext(): ExecutionContext {
+  return {
+    waitUntil(promise: Promise<unknown>) {
+      promise.catch((error) => console.error("[registry] background task failed", error));
+    },
+    passThroughOnException() {},
+    props: {},
+  } as unknown as ExecutionContext;
+}
+
+/** Matches `pattern` (e.g. "/api/workspaces/:id/members") and returns decoded params. */
+export function matchPath(pathname: string, pattern: string): Record<string, string> | null {
+  const names: string[] = [];
+  const regex = new RegExp(
+    `^${pattern.replace(/:[a-zA-Z]+/g, (token) => {
+      names.push(token.slice(1));
+      return "([^/]+)";
+    })}$`,
+  );
+  const match = pathname.match(regex);
+  if (!match) return null;
+  return Object.fromEntries(names.map((name, index) => [name, decodeURIComponent(match[index + 1])]));
+}

package/src/registry-worker/run-events.ts

@@ -0,0 +1,24 @@
+// Run event log and live broadcast, shared by the routes and the cloud dispatcher.
+import type { Env } from "./core.js";
+
+export async function appendRunEvent(env: Env, runId: string, type: string, payload: unknown): Promise<number> {
+  // One statement, so concurrent updates (a run fanned out across browsers
+  // reports from several lanes at once) can't both read the same MAX and
+  // collide on (run_id, sequence).
+  const row = await env.DB.prepare(`
+    INSERT INTO run_events (run_id, sequence, type, payload_json)
+    SELECT ?, COALESCE(MAX(sequence), 0) + 1, ?, ? FROM run_events WHERE run_id = ?
+    RETURNING sequence
+  `).bind(runId, type, JSON.stringify(payload), runId).first<{ sequence: number }>();
+  return row?.sequence ?? 0;
+}
+
+export async function broadcastProjectEvent(env: Env, projectId: string, event: unknown): Promise<void> {
+  if (!env.RUNS_COORDINATOR) return;
+  const stub = env.RUNS_COORDINATOR.get(env.RUNS_COORDINATOR.idFromName(projectId));
+  await stub.fetch("https://runs-coordinator/broadcast", {
+    method: "POST",
+    body: JSON.stringify(event),
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/registry-worker/runner/dispatch.ts

@@ -0,0 +1,219 @@
+// Starts queued cloud work (test runs and discovery tasks) on Bugmole's
+// runner pool. Runs on every cron tick, when cloud work is queued, and when
+// some finishes. Each workspace gets at most its plan's parallel slots, the
+// whole pool at most CLOUD_POOL_MAX, and workspaces take turns so one big
+// queue can't starve the rest.
+import type { Env } from "../core.js";
+import { getEntitlements } from "../billing/entitlements.js";
+import { canSpend } from "../billing/ledger.js";
+import { entitlementMode } from "../billing/enforcement.js";
+import { runQueuedHooks, taskQueuedHooks, type CloudJobKind } from "../hooks.js";
+import { registerJob } from "../jobs/index.js";
+import { announceJob, cloudWorkerId, JOB_TABLE, type CloudJob } from "./jobs.js";
+import { signRunnerToken } from "./tokens.js";
+
+export const DEFAULT_CLOUD_POOL_MAX = 20;
+export const MAX_DISPATCH_ATTEMPTS = 3;
+/** Time a started container has to send its first update. */
+export const START_LEASE_MS = 5 * 60_000;
+const RETRY_DELAY_MS = 30_000;
+/** Plans without a parallel limit (Enterprise) still get a ceiling. */
+const UNLIMITED_PARALLEL = 100;
+
+export type LaunchRequest = { kind: CloudJobKind; id: string; projectId: string; token: string; registryUrl: string };
+
+/** Asks the runner Worker to start a container. Tests replace `start`. */
+export const runnerLauncher = {
+  async start(env: Env, launch: LaunchRequest): Promise<void> {
+    if (!env.RUNNER) throw new Error("The runner service isn't bound to this registry");
+    const result = await env.RUNNER.fetch(`https://runner.internal/jobs/${launch.kind}/${encodeURIComponent(launch.id)}/start`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(launch),
+    });
+    if (!result.ok) throw new Error(`The runner service answered ${result.status}`);
+  },
+};
+
+export function cloudPoolMax(env: Env): number {
+  const value = Number(env.CLOUD_POOL_MAX);
+  return Number.isInteger(value) && value >= 0 ? value : DEFAULT_CLOUD_POOL_MAX;
+}
+
+type QueuedJob = CloudJob & { workspaceId: string; attempts: number; requestedAt: string };
+type Outcome = { started: string[]; retrying: string[]; failed: string[]; expired: string[] };
+
+/** Takes one job per workspace per round until slots or jobs run out. */
+export function pickFairly<T extends { workspaceId: string }>(queued: T[], freeByWorkspace: Map<string, number>, poolFree: number): T[] {
+  const queues = new Map<string, T[]>();
+  for (const job of queued) {
+    const queue = queues.get(job.workspaceId) ?? [];
+    queue.push(job);
+    queues.set(job.workspaceId, queue);
+  }
+  const picked: T[] = [];
+  const free = new Map(freeByWorkspace);
+  let progress = true;
+  while (poolFree > 0 && progress) {
+    progress = false;
+    for (const [workspaceId, queue] of queues) {
+      if (poolFree <= 0) break;
+      if (!queue.length || (free.get(workspaceId) ?? 0) <= 0) continue;
+      picked.push(queue.shift()!);
+      free.set(workspaceId, (free.get(workspaceId) ?? 0) - 1);
+      poolFree -= 1;
+      progress = true;
+    }
+  }
+  return picked;
+}
+
+async function failJob(env: Env, job: CloudJob, previousStatus: string, failureCode: string, message: string) {
+  if (job.kind === "run") {
+    await env.DB.prepare(`
+      UPDATE runs SET status = 'error', failure_code = ?, error_message = ?, completed_at = CURRENT_TIMESTAMP, lease_expires_at = NULL
+      WHERE id = ?
+    `).bind(failureCode, message, job.id).run();
+  } else {
+    await env.DB.prepare(`
+      UPDATE agent_tasks SET status = 'error', error_message = ?, progress_message = ?, completed_at = CURRENT_TIMESTAMP, lease_expires_at = NULL
+      WHERE id = ?
+    `).bind(message, message, job.id).run();
+  }
+  await announceJob(env, job, { status: "error", previousStatus, payload: { status: "error", failureCode, errorMessage: message } });
+}
+
+/** Work whose runner stopped reporting is failed (and billed up to its last heartbeat). */
+async function expireLostJobs(env: Env, now: Date): Promise<string[]> {
+  const nowIso = now.toISOString();
+  const expired: string[] = [];
+  const message = "The cloud runner stopped responding.";
+  for (const kind of ["run", "task"] as const) {
+    const table = JOB_TABLE[kind];
+    const lost = await env.DB.prepare(`
+      SELECT id, project_id AS projectId, workspace_id AS workspaceId FROM ${table}
+      WHERE execution_mode = 'cloud' AND status = 'running' AND lease_expires_at < ?
+    `).bind(nowIso).all<{ id: string; projectId: string; workspaceId: string | null }>();
+    for (const row of lost.results) {
+      const changed = await env.DB.prepare(`
+        UPDATE ${table} SET status = 'error', error_message = ?, completed_at = CURRENT_TIMESTAMP
+          ${kind === "run" ? ", failure_code = 'runner_lost'" : ""}
+        WHERE id = ? AND status = 'running' AND lease_expires_at < ?
+      `).bind(message, row.id, nowIso).run();
+      if ((changed.meta?.changes ?? 0) !== 1) continue;
+      expired.push(row.id);
+      await announceJob(env, { kind, ...row }, { status: "error", previousStatus: "running", payload: { status: "error", failureCode: "runner_lost", errorMessage: message } });
+    }
+  }
+  return expired;
+}
+
+async function queuedJobs(env: Env, nowIso: string): Promise<QueuedJob[]> {
+  const select = (kind: CloudJobKind) => env.DB.prepare(`
+    SELECT '${kind}' AS kind, id, project_id AS projectId, workspace_id AS workspaceId,
+           dispatch_attempts AS attempts, requested_at AS requestedAt
+    FROM ${JOB_TABLE[kind]}
+    WHERE execution_mode = 'cloud' AND status = 'queued' AND workspace_id IS NOT NULL
+      AND (next_dispatch_at IS NULL OR next_dispatch_at <= ?)
+    ORDER BY requested_at ASC LIMIT 500
+  `).bind(nowIso).all<QueuedJob>();
+  const [runs, tasks] = await Promise.all([select("run"), select("task")]);
+  return [...runs.results, ...tasks.results].sort((a, b) => a.requestedAt.localeCompare(b.requestedAt));
+}
+
+async function activeByWorkspace(env: Env): Promise<Map<string, number>> {
+  const rows = await env.DB.prepare(`
+    SELECT workspace_id AS workspaceId, SUM(count) AS count FROM (
+      SELECT workspace_id, COUNT(*) AS count FROM runs WHERE execution_mode = 'cloud' AND status = 'running' GROUP BY workspace_id
+      UNION ALL
+      SELECT workspace_id, COUNT(*) AS count FROM agent_tasks WHERE execution_mode = 'cloud' AND status = 'running' GROUP BY workspace_id
+    ) GROUP BY workspace_id
+  `).all<{ workspaceId: string; count: number }>();
+  return new Map(rows.results.map((row) => [row.workspaceId, Number(row.count)]));
+}
+
+async function claim(env: Env, job: QueuedJob, now: Date): Promise<boolean> {
+  const table = JOB_TABLE[job.kind];
+  const claimed = await env.DB.prepare(`
+    UPDATE ${table} SET status = 'running', worker_id = ?, claimed_at = ?, lease_expires_at = ?,
+      heartbeat_at = CURRENT_TIMESTAMP, started_at = COALESCE(started_at, CURRENT_TIMESTAMP),
+      dispatch_attempts = dispatch_attempts + 1
+      ${job.kind === "task" ? ", attempts = attempts + 1" : ""}
+    WHERE id = ? AND status = 'queued' AND execution_mode = 'cloud'
+  `).bind(cloudWorkerId(job), now.toISOString(), new Date(now.getTime() + START_LEASE_MS).toISOString(), job.id).run();
+  return (claimed.meta?.changes ?? 0) === 1;
+}
+
+async function requeue(env: Env, job: QueuedJob, attempts: number, now: Date) {
+  await env.DB.prepare(`
+    UPDATE ${JOB_TABLE[job.kind]} SET status = 'queued', worker_id = NULL, claimed_at = NULL, lease_expires_at = NULL,
+      started_at = NULL, heartbeat_at = NULL, next_dispatch_at = ?
+    WHERE id = ?
+  `).bind(new Date(now.getTime() + RETRY_DELAY_MS * attempts).toISOString(), job.id).run();
+}
+
+export async function dispatchCloudRuns(env: Env, now = new Date()): Promise<Outcome> {
+  const outcome: Outcome = { started: [], retrying: [], failed: [], expired: [] };
+  outcome.expired = await expireLostJobs(env, now);
+  const queued = await queuedJobs(env, now.toISOString());
+  if (!queued.length) return outcome;
+  if (!env.RUNNER_TOKEN_SECRET) {
+    console.warn("[dispatch] RUNNER_TOKEN_SECRET is not set; cloud work stays queued");
+    return outcome;
+  }
+
+  const active = await activeByWorkspace(env);
+  const poolFree = cloudPoolMax(env) - [...active.values()].reduce((sum, count) => sum + count, 0);
+  if (poolFree <= 0) return outcome;
+  const freeByWorkspace = new Map<string, number>();
+  for (const workspaceId of new Set(queued.map((job) => job.workspaceId))) {
+    const { parallel } = await getEntitlements(env, workspaceId);
+    freeByWorkspace.set(workspaceId, (parallel ?? UNLIMITED_PARALLEL) - (active.get(workspaceId) ?? 0));
+  }
+
+  const registryUrl = (env.REGISTRY_PUBLIC_URL || "https://api.bugmole.com").replace(/\/$/, "");
+  for (const job of pickFairly(queued, freeByWorkspace, poolFree)) {
+    // Minutes may have run out while the job waited.
+    if ((await entitlementMode(env, job.workspaceId)) === "enforce") {
+      const decision = await canSpend(env, job.workspaceId, "browser_minute", 1, now);
+      if (!decision.allowed) {
+        await env.DB.prepare(`UPDATE ${JOB_TABLE[job.kind]} SET blocked_reason = ? WHERE id = ?`).bind(decision.reason, job.id).run();
+        await failJob(env, job, "queued", "plan_limit", decision.message);
+        outcome.failed.push(job.id);
+        continue;
+      }
+    }
+    if (!(await claim(env, job, now))) continue;
+    const attempts = job.attempts + 1;
+    try {
+      const token = await signRunnerToken(env, { kind: job.kind, id: job.id, projectId: job.projectId, workspaceId: job.workspaceId }, now.getTime());
+      await runnerLauncher.start(env, { kind: job.kind, id: job.id, projectId: job.projectId, token, registryUrl });
+      outcome.started.push(job.id);
+      await announceJob(env, job, { status: "running", previousStatus: "queued", payload: { status: "running", workerId: cloudWorkerId(job), attempt: attempts } });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      console.warn(`[dispatch] could not start ${job.kind} ${job.id} (attempt ${attempts}): ${reason}`);
+      if (attempts >= MAX_DISPATCH_ATTEMPTS) {
+        // Never started, so never billed.
+        await env.DB.prepare(`UPDATE ${JOB_TABLE[job.kind]} SET claimed_at = NULL, worker_id = NULL WHERE id = ?`).bind(job.id).run();
+        await failJob(env, job, "queued", "runner_unavailable", "Bugmole Cloud couldn't start a runner. Try again, or run on your own machine.");
+        outcome.failed.push(job.id);
+      } else {
+        await requeue(env, job, attempts, now);
+        outcome.retrying.push(job.id);
+      }
+    }
+  }
+  return outcome;
+}
+
+registerJob("minute", "cloud-dispatch", async (env, _ctx, now) => {
+  await dispatchCloudRuns(env, now);
+});
+
+runQueuedHooks.push(async (env, event) => {
+  if (event.executionMode === "cloud") await dispatchCloudRuns(env);
+});
+taskQueuedHooks.push(async (env, event) => {
+  if (event.executionMode === "cloud") await dispatchCloudRuns(env);
+});

package/src/registry-worker/runner/jobs.ts

@@ -0,0 +1,43 @@
+// Runs and discovery tasks share one cloud pipeline: the same slots, lease,
+// meter and stop rules. This describes where each kind lives and how its
+// changes are announced.
+import type { Env } from "../core.js";
+import { runChangedHooks, taskChangedHooks, type CloudJobKind } from "../hooks.js";
+import { appendRunEvent, broadcastProjectEvent } from "../run-events.js";
+
+export type CloudJob = { kind: CloudJobKind; id: string; projectId: string; workspaceId: string | null };
+
+export const JOB_TABLE: Record<CloudJobKind, "runs" | "agent_tasks"> = { run: "runs", task: "agent_tasks" };
+/** The status a job ends in when Bugmole gives up on it. */
+export const FAILED_STATUS: Record<CloudJobKind, string> = { run: "error", task: "error" };
+export const TERMINAL_STATUSES: Record<CloudJobKind, Set<string>> = {
+  run: new Set(["success", "partial", "error", "cancelled"]),
+  task: new Set(["completed", "error"]),
+};
+
+export function cloudWorkerId(job: Pick<CloudJob, "kind" | "id">): string {
+  return job.kind === "run" ? `cloud:${job.id}` : `cloud:task:${job.id}`;
+}
+
+export type JobChange = { status: string; previousStatus: string; payload: Record<string, unknown> };
+
+/** Tells the dashboard and the lifecycle hooks what the dispatcher did. */
+export async function announceJob(env: Env, job: CloudJob, change: JobChange): Promise<void> {
+  const terminal = TERMINAL_STATUSES[job.kind].has(change.status);
+  const base = { projectId: job.projectId, workspaceId: job.workspaceId, executionMode: "cloud", status: change.status, previousStatus: change.previousStatus, terminal, fromDispatcher: true };
+  const run = async (work: () => Promise<void>) => {
+    try {
+      await work();
+    } catch (error) {
+      console.error("[dispatch] lifecycle hook failed", error);
+    }
+  };
+  if (job.kind === "run") {
+    await appendRunEvent(env, job.id, change.status === "running" ? "running" : "failed", change.payload);
+    await broadcastProjectEvent(env, job.projectId, { type: "run_event", runId: job.id, eventType: change.status, ...change.payload });
+    for (const hook of runChangedHooks) await run(() => hook(env, { ...base, runId: job.id }));
+  } else {
+    await broadcastProjectEvent(env, job.projectId, { type: "task_event", taskId: job.id, projectId: job.projectId, ...change.payload });
+    for (const hook of taskChangedHooks) await run(() => hook(env, { ...base, taskId: job.id }));
+  }
+}

package/src/registry-worker/runner/metering.ts

@@ -0,0 +1,82 @@
+// Bills finished cloud work from times the registry recorded itself, never
+// from what the runner reports: claimed → finished, but no later than a
+// minute after the last heartbeat, so a runner that vanished isn't billed
+// for the time it took to notice.
+import type { Env } from "../core.js";
+import { recordUsage } from "../billing/ledger.js";
+import { checkUsageThresholds } from "../billing/thresholds.js";
+import { runChangedHooks, taskChangedHooks, type CloudJobKind } from "../hooks.js";
+import { dispatchCloudRuns } from "./dispatch.js";
+import { JOB_TABLE } from "./jobs.js";
+
+const MINUTE = 60_000;
+
+/** Reads both ISO strings and SQLite's CURRENT_TIMESTAMP ("YYYY-MM-DD HH:MM:SS", UTC). */
+export function sqlTime(value: string | null | undefined): number {
+  if (!value) return NaN;
+  return Date.parse(/[zZ]|[+-]\d\d:\d\d$/.test(value) ? value : `${value.replace(" ", "T")}Z`);
+}
+
+export function elapsedMinutes(claimedAt: string, now: number): number {
+  const start = sqlTime(claimedAt);
+  return Number.isFinite(start) ? Math.max(0, Math.ceil((now - start) / MINUTE)) : 0;
+}
+
+export function billableMinutes(
+  times: { claimedAt: string; completedAt: string | null; heartbeatAt: string | null },
+  now = Date.now(),
+): number {
+  const start = sqlTime(times.claimedAt);
+  if (!Number.isFinite(start)) return 0;
+  const completed = sqlTime(times.completedAt);
+  const heartbeat = sqlTime(times.heartbeatAt);
+  let end = Number.isFinite(completed) ? completed : now;
+  if (Number.isFinite(heartbeat)) end = Math.min(end, heartbeat + MINUTE);
+  return Math.max(1, Math.ceil(Math.max(0, end - start) / MINUTE));
+}
+
+/** Records the job's minutes once. Returns them, or null when there was nothing to bill. */
+export async function meterCloudJob(env: Env, kind: CloudJobKind, id: string, now = new Date()): Promise<number | null> {
+  const table = JOB_TABLE[kind];
+  const job = await env.DB.prepare(`
+    SELECT project_id AS projectId, workspace_id AS workspaceId, execution_mode AS executionMode,
+           claimed_at AS claimedAt, completed_at AS completedAt, heartbeat_at AS heartbeatAt, billed_at AS billedAt
+    FROM ${table} WHERE id = ?
+  `).bind(id).first<{
+    projectId: string; workspaceId: string | null; executionMode: string;
+    claimedAt: string | null; completedAt: string | null; heartbeatAt: string | null; billedAt: string | null;
+  }>();
+  // Work that never reached a runner costs nothing.
+  if (!job || job.executionMode !== "cloud" || job.billedAt || !job.claimedAt || !job.workspaceId) return null;
+  const minutes = billableMinutes({ claimedAt: job.claimedAt, completedAt: job.completedAt, heartbeatAt: job.heartbeatAt }, now.getTime());
+  await recordUsage(env, {
+    workspaceId: job.workspaceId,
+    projectId: job.projectId,
+    runId: kind === "run" ? id : null,
+    kind: "browser_minute",
+    quantity: minutes,
+    source: "cloud_run",
+    idempotencyKey: `${kind}:${id}`,
+    ...(kind === "task" ? { meta: { taskId: id } } : {}),
+    now,
+  });
+  await env.DB.prepare(`UPDATE ${table} SET billed_at = ?, billed_minutes = ? WHERE id = ? AND billed_at IS NULL`)
+    .bind(now.toISOString(), minutes, id).run();
+  return minutes;
+}
+
+/** Kept for callers that only deal with runs. */
+export function meterCloudRun(env: Env, runId: string, now = new Date()): Promise<number | null> {
+  return meterCloudJob(env, "run", runId, now);
+}
+
+async function finished(env: Env, kind: CloudJobKind, event: { executionMode: string; terminal: boolean; workspaceId: string | null; fromDispatcher?: boolean }, id: string) {
+  if (event.executionMode !== "cloud" || !event.terminal) return;
+  const minutes = await meterCloudJob(env, kind, id);
+  if (minutes !== null && event.workspaceId) await checkUsageThresholds(env, event.workspaceId);
+  // A slot just opened up.
+  if (!event.fromDispatcher) await dispatchCloudRuns(env);
+}
+
+runChangedHooks.push((env, event) => finished(env, "run", event, event.runId));
+taskChangedHooks.push((env, event) => finished(env, "task", event, event.taskId));

package/src/registry-worker/runner/policy.ts

@@ -0,0 +1,59 @@
+// Rules cloud work must satisfy before and while it runs.
+import type { Env } from "../core.js";
+import { response } from "../core.js";
+import { canSpend } from "../billing/ledger.js";
+import { entitlementMode } from "../billing/enforcement.js";
+import { heartbeatChecks, type JobHeartbeat } from "../hooks.js";
+import { JOB_TABLE } from "./jobs.js";
+import { elapsedMinutes } from "./metering.js";
+
+export const DEFAULT_CLOUD_RUN_MAX_MINUTES = 60;
+
+export function cloudRunMaxMinutes(env: Env): number {
+  const value = Number(env.CLOUD_RUN_MAX_MINUTES);
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_CLOUD_RUN_MAX_MINUTES;
+}
+
+/**
+ * A cloud runner starts from a clean container, so it can only read plans and
+ * save evidence where Bugmole can reach them: Bugmole storage.
+ */
+export async function cloudStorageError(env: Env, projectId: string): Promise<Response | null> {
+  const row = await env.DB.prepare("SELECT storage_mode AS storageMode FROM projects WHERE id = ?")
+    .bind(projectId).first<{ storageMode: string }>();
+  if (row?.storageMode === "managed") return null;
+  return response({
+    error: "Cloud runs need this project to use Bugmole storage, so the runner can read its plans and save evidence. Change storage in Manage → Projects, or run on your own machine.",
+    code: "cloud_needs_managed_storage",
+  }, 422);
+}
+
+/** Stops cloud work that outlived the time limit or the workspace's minutes. */
+async function cloudLimits(env: Env, job: JobHeartbeat) {
+  if (job.executionMode !== "cloud" || !job.workspaceId) return null;
+  const now = Date.now();
+  const active = await env.DB.prepare(`
+    SELECT 'run' AS kind, id, claimed_at AS claimedAt FROM runs
+      WHERE workspace_id = ? AND execution_mode = 'cloud' AND status = 'running' AND claimed_at IS NOT NULL
+    UNION ALL
+    SELECT 'task' AS kind, id, claimed_at AS claimedAt FROM agent_tasks
+      WHERE workspace_id = ? AND execution_mode = 'cloud' AND status = 'running' AND claimed_at IS NOT NULL
+  `).bind(job.workspaceId, job.workspaceId).all<{ kind: string; id: string; claimedAt: string }>();
+  const own = active.results.find((row) => row.kind === job.kind && row.id === job.id);
+  if (!own) return null;
+  let stop: { reason: string; message: string } | null = null;
+  if (elapsedMinutes(own.claimedAt, now) > cloudRunMaxMinutes(env)) {
+    stop = { reason: "time_limit", message: `Cloud work stops after ${cloudRunMaxMinutes(env)} minutes.` };
+  } else if ((await entitlementMode(env, job.workspaceId)) === "enforce") {
+    // Minutes of everything still going count, not just this job.
+    const inFlight = active.results.reduce((sum, row) => sum + elapsedMinutes(row.claimedAt, now), 0);
+    const decision = await canSpend(env, job.workspaceId, "browser_minute", inFlight);
+    if (!decision.allowed) stop = { reason: decision.reason, message: decision.message };
+  }
+  if (stop) {
+    await env.DB.prepare(`UPDATE ${JOB_TABLE[job.kind]} SET blocked_reason = ? WHERE id = ?`).bind(stop.reason, job.id).run();
+  }
+  return stop;
+}
+
+heartbeatChecks.push(cloudLimits);