@bugmole/cli 0.4.0

package/src/registry-worker/artifacts.ts

@@ -0,0 +1,85 @@
+/**
+ * Read-only access to run evidence in the artifacts bucket, for the hosted dashboard.
+ *
+ * The cloud worker writes run evidence under `projects/<id>/...`. These routes let a project member
+ * list and read keys under that prefix and nothing else, so one project can never read another's.
+ */
+
+/** The slice of the R2 binding these routes use, so tests can pass a fake bucket. */
+export type ArtifactBucket = {
+  list(options: {
+    prefix: string;
+    cursor?: string;
+    limit?: number;
+    include?: Array<"httpMetadata" | "customMetadata">;
+  }): Promise<{
+    objects: Array<{ key: string; size: number; uploaded: Date; httpMetadata?: { contentType?: string } }>;
+    truncated: boolean;
+    cursor?: string;
+  }>;
+  get(key: string): Promise<{ body: ReadableStream; size: number; httpMetadata?: { contentType?: string } } | null>;
+};
+
+export const ARTIFACT_STORAGE_UNCONFIGURED = "Artifact storage is not configured";
+const LIST_LIMIT = 1000;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json; charset=utf-8" } });
+}
+
+export function artifactProjectPrefix(projectId: string): string {
+  return `projects/${encodeURIComponent(projectId)}/`;
+}
+
+/** A key is readable only under the project's own prefix, with no `.` or `..` segments. */
+export function isProjectArtifactKey(projectId: string, key: string): boolean {
+  if (!key.startsWith(artifactProjectPrefix(projectId))) return false;
+  return !key.split("/").some((segment) => segment === "." || segment === "..");
+}
+
+/** The prefix to list: the project's whole prefix by default, or a narrower one inside it. */
+export function normalizeArtifactPrefix(projectId: string, prefix: string | null): string | null {
+  const value = prefix?.trim() || artifactProjectPrefix(projectId);
+  return isProjectArtifactKey(projectId, value) ? value : null;
+}
+
+/** A run may record exactly its own manifest key, as the worker writes it. */
+export function isRunManifestKey(projectId: string, runId: string, key: unknown): key is string {
+  return typeof key === "string" && key === `${artifactProjectPrefix(projectId)}runs/${encodeURIComponent(runId)}/manifest.json`;
+}
+
+export async function listProjectArtifacts(bucket: ArtifactBucket | undefined, projectId: string, url: URL): Promise<Response> {
+  if (!bucket) return json({ error: ARTIFACT_STORAGE_UNCONFIGURED }, 503);
+  const prefix = normalizeArtifactPrefix(projectId, url.searchParams.get("prefix"));
+  if (!prefix) return json({ error: "prefix must stay under this project's artifacts" }, 400);
+  const listed = await bucket.list({
+    prefix,
+    cursor: url.searchParams.get("cursor") || undefined,
+    limit: LIST_LIMIT,
+    include: ["httpMetadata"],
+  });
+  return json({
+    objects: listed.objects.map((object) => ({
+      key: object.key,
+      size: object.size,
+      modifiedAt: object.uploaded.toISOString(),
+      contentType: object.httpMetadata?.contentType,
+    })),
+    ...(listed.truncated && listed.cursor ? { cursor: listed.cursor } : {}),
+  });
+}
+
+export async function getProjectArtifact(bucket: ArtifactBucket | undefined, projectId: string, url: URL): Promise<Response> {
+  if (!bucket) return json({ error: ARTIFACT_STORAGE_UNCONFIGURED }, 503);
+  const key = url.searchParams.get("key") ?? "";
+  if (!isProjectArtifactKey(projectId, key)) return json({ error: "key must stay under this project's artifacts" }, 400);
+  const object = await bucket.get(key);
+  if (!object) return json({ error: "Artifact not found" }, 404);
+  return new Response(object.body, {
+    headers: {
+      "content-type": object.httpMetadata?.contentType || "application/octet-stream",
+      "content-length": String(object.size),
+      "cache-control": "private, max-age=60",
+    },
+  });
+}

package/src/registry-worker/billing/billing-core.test.ts

@@ -0,0 +1,175 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { call, createTestEnv, runScheduled, seedPlan, seedProject } from "../testing/harness.js";
+import { canSpend, recordUsage, usagePeriod, usageSummary } from "./ledger.js";
+import { checkUsageThresholds } from "./thresholds.js";
+import { enforceRetention } from "../jobs/retention.js";
+
+test("usage periods follow the subscription day, clamped to short months", () => {
+  assert.deepEqual(usagePeriod(null, new Date("2026-09-17T10:00:00Z")), {
+    start: "2026-09-01T00:00:00.000Z",
+    end: "2026-10-01T00:00:00.000Z",
+  });
+  const jan31 = "2026-01-31T08:00:00.000Z";
+  assert.deepEqual(usagePeriod(jan31, new Date("2026-02-28T09:00:00Z")), {
+    start: "2026-02-28T08:00:00.000Z",
+    end: "2026-03-31T08:00:00.000Z",
+  });
+  assert.deepEqual(usagePeriod(jan31, new Date("2026-02-15T00:00:00Z")), {
+    start: "2026-01-31T08:00:00.000Z",
+    end: "2026-02-28T08:00:00.000Z",
+  });
+  assert.equal(usagePeriod("2026-12-10T00:00:00.000Z", new Date("2027-01-05T00:00:00Z")).start, "2026-12-10T00:00:00.000Z");
+});
+
+test("usage is recorded once per key and Free stops at its allowance", async () => {
+  const { env } = createTestEnv();
+  const { workspaceId } = await seedProject(env);
+  const record = { workspaceId, kind: "browser_minute" as const, quantity: 290, source: "cloud_run" as const, idempotencyKey: "run:1" };
+  assert.equal(await recordUsage(env, record), true);
+  assert.equal(await recordUsage(env, record), false, "same key twice");
+  assert.deepEqual(await canSpend(env, workspaceId, "browser_minute", 10), { allowed: true });
+  const over = await canSpend(env, workspaceId, "browser_minute", 11);
+  assert.equal(over.allowed, false);
+  assert.equal(!over.allowed && over.reason, "quota");
+  assert.equal((await canSpend(env, workspaceId, "device_minute", 1)).allowed, false, "Free has no real devices");
+  const { summary } = await usageSummary(env, workspaceId);
+  assert.equal(summary.lines.browser_minute.used, 290);
+  assert.equal(summary.lines.browser_minute.remaining, 10);
+  assert.equal(summary.overageCents, 0);
+});
+
+test("paid plans bill beyond the allowance until the spending limit", async () => {
+  const { env, db } = createTestEnv();
+  const { workspaceId } = await seedProject(env);
+  db.db.prepare("INSERT INTO workspace_plans (workspace_id, plan, spending_limit_cents) VALUES (?, 'team', 1000)").run(workspaceId);
+  await recordUsage(env, { workspaceId, kind: "browser_minute", quantity: 3_200, source: "cloud_run", idempotencyKey: "a" });
+  const { summary } = await usageSummary(env, workspaceId);
+  assert.equal(summary.lines.browser_minute.overageQuantity, 200);
+  assert.equal(summary.overageCents, 800, "200 minutes × $0.04");
+  assert.equal((await canSpend(env, workspaceId, "browser_minute", 50)).allowed, true, "$10.00 exactly");
+  const blocked = await canSpend(env, workspaceId, "browser_minute", 51);
+  assert.equal(!blocked.allowed && blocked.reason, "spending_limit");
+  assert.equal((await canSpend(env, workspaceId, "ai_credit", 1_500)).allowed, true, "credits are still in the allowance");
+});
+
+test("a failed payment pauses cloud usage once its grace period ends", async () => {
+  const { env, db } = createTestEnv();
+  const { workspaceId } = await seedProject(env);
+  db.db.prepare("INSERT INTO workspace_plans (workspace_id, plan, status, grace_until) VALUES (?, 'team', 'past_due', ?)")
+    .run(workspaceId, new Date(Date.now() + 86_400_000).toISOString());
+  assert.equal((await canSpend(env, workspaceId, "browser_minute", 1)).allowed, true);
+  db.db.prepare("UPDATE workspace_plans SET grace_until = ? WHERE workspace_id = ?").run(new Date(Date.now() - 1000).toISOString(), workspaceId);
+  const paused = await canSpend(env, workspaceId, "browser_minute", 1);
+  assert.equal(!paused.allowed && paused.reason, "suspended");
+});
+
+test("owners and billing managers get one email per threshold per period", async () => {
+  const { env, email } = createTestEnv({ DASHBOARD_URL: "https://dash.test" });
+  const { workspaceId, owner } = await seedProject(env);
+  await call(env, "GET", "/api/workspaces", { as: owner, headers: { "x-aegis-email": "Owner@Acme.test" } });
+  await recordUsage(env, { workspaceId, kind: "ai_credit", quantity: 85, source: "ai", idempotencyKey: "x" });
+  await checkUsageThresholds(env, workspaceId);
+  await checkUsageThresholds(env, workspaceId);
+  assert.equal(email.sent.length, 1);
+  assert.equal(email.sent[0].to[0].email, "owner@acme.test");
+  assert.match(email.sent[0].subject, /80% of this month's AI credits/);
+  await recordUsage(env, { workspaceId, kind: "ai_credit", quantity: 15, source: "ai", idempotencyKey: "y" });
+  await checkUsageThresholds(env, workspaceId);
+  assert.equal(email.sent.length, 2);
+  assert.match(email.sent[1].subject, /all of this month's AI credits/);
+  assert.match(email.sent[1].text, /dash\.test\/billing/);
+});
+
+test("the usage route shows plan, meters and who may change the limit", async () => {
+  const { env, db } = createTestEnv();
+  const { workspaceId, owner } = await seedProject(env);
+  const free = await call(env, "GET", `/api/workspaces/${workspaceId}/usage`, { as: owner });
+  assert.equal(free.status, 200);
+  assert.equal(free.json.plan.id, "free");
+  assert.equal(free.json.usage.lines.browser_minute.included, 300);
+  assert.equal((await call(env, "PUT", `/api/workspaces/${workspaceId}/billing/spending-limit`, { as: owner, body: { limitCents: 500 } })).status, 409);
+
+  db.db.prepare("INSERT INTO workspace_plans (workspace_id, plan) VALUES (?, 'business')").run(workspaceId);
+  const set = await call(env, "PUT", `/api/workspaces/${workspaceId}/billing/spending-limit`, { as: owner, body: { limitCents: 25_000 } });
+  assert.equal(set.status, 200);
+  const after = await call(env, "GET", `/api/workspaces/${workspaceId}/usage`, { as: owner });
+  assert.equal(after.json.usage.spendingLimitCents, 25_000);
+  assert.equal(after.json.limits.parallel, 25);
+  assert.equal((await call(env, "PUT", `/api/workspaces/${workspaceId}/billing/spending-limit`, { as: owner, body: { limitCents: -1 } })).status, 422);
+  assert.equal((await call(env, "GET", `/api/workspaces/${workspaceId}/usage`, { as: "user_stranger" })).status, 403);
+});
+
+test("with limits enforced, Free gets one project and cloud runs need the rollout and minutes", async () => {
+  const { env, db } = createTestEnv({ FEATURE_ENTITLEMENTS: "on", FEATURE_CLOUD_RUNNERS: "beta" });
+  const { workspaceId, owner, projectId } = await seedProject(env, { storageProvider: "bugmole" });
+  const second = await call(env, "POST", "/api/projects/register", {
+    as: owner,
+    body: { id: "second", name: "Second", workspaceId, environment: "staging", storageProvider: "r2" },
+  });
+  assert.equal(second.status, 402);
+  assert.equal(second.json.limit, "projects");
+
+  await seedPlan(env, projectId, owner);
+  const cloud = (key: string) =>
+    call(env, "POST", `/api/projects/${projectId}/runs`, {
+      as: owner,
+      headers: { "x-aegis-email": "owner@acme.test", "x-aegis-email-verified": "true" },
+      body: { planId: "checkout", idempotencyKey: key, executionMode: "cloud" },
+    });
+  assert.equal((await cloud("c1")).json.code, "cloud_unavailable");
+  db.db.prepare("INSERT INTO workspace_flags (workspace_id, flag) VALUES (?, 'cloud_runners')").run(workspaceId);
+  const queued = await cloud("c2");
+  assert.equal(queued.status, 201);
+  assert.equal(queued.json.run.executionMode, "cloud");
+
+  const claim = await call(env, "POST", `/api/runs/${queued.json.run.id}/claim`, { as: owner, body: { workerId: "laptop" } });
+  assert.equal(claim.status, 409, "customer workers can't take cloud runs");
+
+  await recordUsage(env, { workspaceId, kind: "browser_minute", quantity: 300, source: "cloud_run", idempotencyKey: "used" });
+  const exhausted = await cloud("c3");
+  assert.equal(exhausted.status, 402);
+  assert.equal(exhausted.json.limit, "cloud_minutes");
+
+  const local = await call(env, "POST", `/api/projects/${projectId}/runs`, { as: owner, body: { planId: "checkout", idempotencyKey: "l1" } });
+  assert.equal(local.status, 201, "runs on your own machine are never capped");
+  assert.equal(local.json.run.executionMode, "self");
+});
+
+test("shadow mode logs a limit without blocking", async () => {
+  const { env } = createTestEnv({ FEATURE_ENTITLEMENTS: "shadow" });
+  const { workspaceId, owner } = await seedProject(env);
+  const second = await call(env, "POST", "/api/projects/register", {
+    as: owner,
+    body: { id: "second", name: "Second", workspaceId, environment: "staging", storageProvider: "r2" },
+  });
+  assert.equal(second.status, 201);
+});
+
+test("expired run history and its evidence are deleted daily", async () => {
+  const { env, db, artifacts } = createTestEnv({ FEATURE_ENTITLEMENTS: "on" });
+  const { workspaceId, owner, projectId } = await seedProject(env);
+  await seedPlan(env, projectId, owner);
+  const make = async (key: string) =>
+    (await call(env, "POST", `/api/projects/${projectId}/runs`, { as: owner, body: { planId: "checkout", idempotencyKey: key } })).json.run.id as string;
+  const oldRun = await make("old");
+  const newRun = await make("new");
+  const oldDate = new Date(Date.now() - 10 * 86_400_000).toISOString();
+  db.db.prepare("UPDATE runs SET status = 'success', completed_at = ?, requested_at = ? WHERE id = ?").run(oldDate, oldDate, oldRun);
+  db.db.prepare("UPDATE runs SET status = 'success', completed_at = ? WHERE id = ?").run(new Date().toISOString(), newRun);
+  await artifacts.put(`projects/${projectId}/runs/${oldRun}/manifest.json`, "{}");
+  await artifacts.put(`projects/${projectId}/runs/${newRun}/manifest.json`, "{}");
+
+  const listed = await call(env, "GET", `/api/projects/${projectId}/runs`, { as: owner });
+  assert.deepEqual(listed.json.runs.map((run: { id: string }) => run.id), [newRun], "Free shows 7 days even before cleanup");
+
+  await runScheduled(env, "17 3 * * *");
+  assert.equal(db.db.prepare("SELECT COUNT(*) AS c FROM runs WHERE id = ?").get(oldRun)?.c, 0);
+  assert.equal(db.db.prepare("SELECT COUNT(*) AS c FROM runs WHERE id = ?").get(newRun)?.c, 1);
+  assert.deepEqual([...artifacts.objects.keys()], [`projects/${projectId}/runs/${newRun}/manifest.json`]);
+  const audit = await call(env, "GET", `/api/workspaces/${workspaceId}/audit-log`, { as: owner });
+  assert.ok(audit.json.entries.some((entry: { action: string }) => entry.action === "runs.expired"));
+
+  db.db.prepare("INSERT INTO workspace_plans (workspace_id, plan) VALUES (?, 'business')").run(workspaceId);
+  assert.deepEqual(await enforceRetention(env), { runs: 0, objects: 0 });
+});

package/src/registry-worker/billing/checkout-routes.ts

@@ -0,0 +1,209 @@
+// Routes for buying, changing and cancelling a plan, receipts, the billing
+// contact, and the provider's webhook; plus the daily billing jobs.
+import { PLANS, type BillingInterval } from "../../billing/plan-catalog.js";
+import type { Env } from "../core.js";
+import { memberOfWorkspace, requestJson, response } from "../core.js";
+import { flagOn } from "../flags.js";
+import { registerJob } from "../jobs/index.js";
+import { actorOf, recordAudit } from "../org/audit.js";
+import { matchPath, registerPublicRoutes, registerRoutes, type AuthedRouteContext } from "../routes/index.js";
+import { defaultBillingProvider } from "./provider.js";
+import {
+  BillingError,
+  cancelAtPeriodEnd,
+  chaseOverdueInvoices,
+  closeUsagePeriods,
+  completeCheckout,
+  handleProviderWebhook,
+  isPaidPlan,
+  periodPriceCents,
+  startCheckout,
+  syncAllBilling,
+} from "./subscriptions.js";
+
+/** Printed on every receipt. Bugmole isn't a merchant of record: taxes are the customer's to account for. */
+export const SELLER = {
+  name: "The AI Inc.",
+  product: "Bugmole",
+  email: "info@theaiinc.com",
+  website: "https://bugmole.com",
+};
+
+function billingError(error: unknown): Response {
+  if (error instanceof BillingError) return response({ error: error.message, code: error.code }, error.status);
+  console.error("[billing] request failed", error);
+  return response({ error: "Billing is unavailable right now. Try again shortly.", code: "billing_error" }, 502);
+}
+
+async function mayManage(context: AuthedRouteContext, workspaceId: string): Promise<Response | null> {
+  if (await memberOfWorkspace(context.env, context.principal, workspaceId, "billing.manage")) return null;
+  return response({ error: "Only owners and billing managers can change billing" }, 403);
+}
+
+async function billingEnabled(env: Env, workspaceId: string): Promise<boolean> {
+  return flagOn(env, workspaceId, "billing");
+}
+
+async function overview({ env, principal }: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId))) return response({ error: "Workspace scope is not allowed" }, 403);
+  const canManage = await memberOfWorkspace(env, principal, workspaceId, "billing.manage");
+  const row = await env.DB.prepare(`
+    SELECT plan, billing_interval AS interval, status, current_period_end AS periodEnd, cancel_at_period_end AS cancelAtPeriodEnd,
+           pending_plan AS pendingPlan, billing_email AS email, billing_name AS name, billing_address AS address, tax_id AS taxId
+    FROM workspace_plans WHERE workspace_id = ?
+  `).bind(workspaceId).first<Record<string, string | number | null>>();
+  const scheduled = await env.DB.prepare(`
+    SELECT plan, billing_interval AS interval FROM billing_checkouts WHERE workspace_id = ? AND status = 'scheduled' ORDER BY completed_at DESC LIMIT 1
+  `).bind(workspaceId).first<{ plan: string; interval: string }>();
+  const invoices = canManage
+    ? await env.DB.prepare(`
+        SELECT id, number, kind, status, plan, period_start AS periodStart, period_end AS periodEnd, currency,
+               total_cents AS totalCents, refunded_cents AS refundedCents, provider_url AS payUrl, due_at AS dueAt, paid_at AS paidAt, created_at AS createdAt
+        FROM invoices WHERE workspace_id = ? AND status != 'none' ORDER BY created_at DESC LIMIT 50
+      `).bind(workspaceId).all()
+    : { results: [] };
+  const provider = defaultBillingProvider(env);
+  const enabled = await billingEnabled(env, workspaceId);
+  const offers = (["team", "business"] as const).flatMap((plan) => (["month", "year"] as const).map((interval) => ({
+    plan,
+    interval,
+    priceCents: periodPriceCents(plan, interval),
+    available: enabled && provider.canSell(env, plan, interval),
+  })));
+  return response({
+    canManage,
+    subscription: row && row.status !== "canceled" && isPaidPlan(row.plan)
+      ? {
+        plan: row.plan,
+        interval: row.interval,
+        status: row.status,
+        periodEnd: row.periodEnd,
+        renews: !row.cancelAtPeriodEnd,
+        changesTo: scheduled ? { plan: scheduled.plan, interval: scheduled.interval } : row.cancelAtPeriodEnd ? { plan: "free", interval: null } : null,
+      }
+      : null,
+    offers,
+    contact: canManage && row ? { name: row.name, email: row.email, address: row.address, taxId: row.taxId } : null,
+    invoices: invoices.results,
+  });
+}
+
+async function checkout(context: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  const denied = await mayManage(context, workspaceId);
+  if (denied) return denied;
+  if (!(await billingEnabled(context.env, workspaceId))) {
+    return response({ error: "Online checkout isn't open yet. Contact us to upgrade.", code: "billing_unavailable" }, 503);
+  }
+  const body = await requestJson(context.request);
+  const plan = body?.plan;
+  const interval = body?.interval as BillingInterval;
+  if (!isPaidPlan(plan) || (interval !== "month" && interval !== "year")) {
+    return response({ error: "plan must be team or business, and interval month or year" }, 422);
+  }
+  try {
+    return response(await startCheckout(context.env, context.principal, workspaceId, plan, interval, context.request), 201);
+  } catch (error) {
+    return billingError(error);
+  }
+}
+
+async function complete(context: AuthedRouteContext, workspaceId: string, checkoutId: string): Promise<Response> {
+  const denied = await mayManage(context, workspaceId);
+  if (denied) return denied;
+  try {
+    const result = await completeCheckout(context.env, workspaceId, checkoutId);
+    return response({ status: result.status, plan: { id: result.plan.plan, name: PLANS[result.plan.plan].name, interval: result.plan.interval, periodEnd: result.plan.periodEnd } });
+  } catch (error) {
+    return billingError(error);
+  }
+}
+
+async function cancel(context: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  const denied = await mayManage(context, workspaceId);
+  if (denied) return denied;
+  try {
+    const plan = await cancelAtPeriodEnd(context.env, context.principal, workspaceId, context.request);
+    return response({ plan: { id: plan.plan, periodEnd: plan.periodEnd } });
+  } catch (error) {
+    return billingError(error);
+  }
+}
+
+const CONTACT_LIMITS = { name: 120, email: 254, address: 500, taxId: 64 } as const;
+
+async function updateContact(context: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  const denied = await mayManage(context, workspaceId);
+  if (denied) return denied;
+  const body = await requestJson(context.request);
+  const values: Record<keyof typeof CONTACT_LIMITS, string | null> = { name: null, email: null, address: null, taxId: null };
+  for (const key of Object.keys(CONTACT_LIMITS) as Array<keyof typeof CONTACT_LIMITS>) {
+    const value = body?.[key];
+    if (value === undefined || value === null || value === "") continue;
+    if (typeof value !== "string" || value.trim().length > CONTACT_LIMITS[key]) return response({ error: `${key} is too long` }, 422);
+    values[key] = value.trim();
+  }
+  if (values.email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(values.email)) return response({ error: "email isn't valid" }, 422);
+  await context.env.DB.prepare(`
+    INSERT INTO workspace_plans (workspace_id, plan, billing_name, billing_email, billing_address, tax_id)
+    VALUES (?, 'free', ?, ?, ?, ?)
+    ON CONFLICT(workspace_id) DO UPDATE SET billing_name = excluded.billing_name, billing_email = excluded.billing_email,
+      billing_address = excluded.billing_address, tax_id = excluded.tax_id, updated_at = CURRENT_TIMESTAMP
+  `).bind(workspaceId, values.name, values.email, values.address, values.taxId).run();
+  await recordAudit(context.env, actorOf(context.principal), { workspaceId, action: "billing.contact_updated" }, context.request);
+  return response({ contact: values });
+}
+
+async function invoice(context: AuthedRouteContext, workspaceId: string, invoiceId: string): Promise<Response> {
+  const denied = await mayManage(context, workspaceId);
+  if (denied) return denied;
+  const row = await context.env.DB.prepare(`
+    SELECT i.id, i.number, i.kind, i.status, i.plan, i.period_start AS periodStart, i.period_end AS periodEnd, i.currency,
+           i.total_cents AS totalCents, i.refunded_cents AS refundedCents, i.lines_json AS linesJson, i.provider,
+           i.provider_ref AS providerRef, i.provider_url AS payUrl, i.due_at AS dueAt, i.paid_at AS paidAt, i.created_at AS createdAt,
+           w.name AS workspaceName, p.billing_name AS billingName, p.billing_email AS billingEmail,
+           p.billing_address AS billingAddress, p.tax_id AS taxId
+    FROM invoices i
+    JOIN workspaces w ON w.id = i.workspace_id
+    LEFT JOIN workspace_plans p ON p.workspace_id = i.workspace_id
+    WHERE i.id = ? AND i.workspace_id = ? AND i.status != 'none'
+  `).bind(invoiceId, workspaceId).first<Record<string, unknown> & { linesJson: string }>();
+  if (!row) return response({ error: "Invoice not found" }, 404);
+  const { linesJson, ...rest } = row;
+  return response({
+    invoice: { ...rest, lines: JSON.parse(linesJson) },
+    seller: SELLER,
+    note: "Prices exclude taxes. Bugmole is sold by The AI Inc.; any sales tax or VAT due in your country is yours to account for.",
+  });
+}
+
+registerRoutes(async (context) => {
+  const { request, url } = context;
+  let params = matchPath(url.pathname, "/api/workspaces/:workspaceId/billing");
+  if (params && request.method === "GET") return overview(context, params.workspaceId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/billing/checkout");
+  if (params && request.method === "POST") return checkout(context, params.workspaceId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/billing/checkout/:checkoutId/complete");
+  if (params && request.method === "POST") return complete(context, params.workspaceId, params.checkoutId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/billing/cancel");
+  if (params && request.method === "POST") return cancel(context, params.workspaceId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/billing/contact");
+  if (params && request.method === "PUT") return updateContact(context, params.workspaceId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/invoices/:invoiceId");
+  if (params && request.method === "GET") return invoice(context, params.workspaceId, params.invoiceId);
+  return null;
+});
+
+// The provider calls this; it proves itself with its own signature.
+registerPublicRoutes(async ({ request, env, url }) => {
+  const params = matchPath(url.pathname, "/api/billing/webhooks/:provider");
+  if (!params || request.method !== "POST") return null;
+  return handleProviderWebhook(env, params.provider, request);
+});
+
+registerJob("daily", "billing-sync", async (env, _ctx, now) => {
+  await syncAllBilling(env, now);
+});
+registerJob("daily", "billing-close", async (env, _ctx, now) => {
+  await closeUsagePeriods(env, now);
+  await chaseOverdueInvoices(env, now);
+});

package/src/registry-worker/billing/enforcement.ts

@@ -0,0 +1,69 @@
+// Plan limits at the points where they apply. The "entitlements" flag lets
+// limits run in shadow mode first: violations are logged, nothing is blocked.
+import type { Env } from "../core.js";
+import { response } from "../core.js";
+import { flagMode, flagOn } from "../flags.js";
+import { getEntitlements } from "./entitlements.js";
+import { canSpend } from "./ledger.js";
+
+export type EnforcementMode = "enforce" | "shadow" | "off";
+
+export async function entitlementMode(env: Env, workspaceId: string | null): Promise<EnforcementMode> {
+  const mode = flagMode(env, "entitlements");
+  if (mode === "on") return "enforce";
+  if (mode === "shadow") return "shadow";
+  if (mode === "off" || !workspaceId) return "off";
+  return (await flagOn(env, workspaceId, "entitlements")) ? "enforce" : "off";
+}
+
+function planLimit(message: string, limit: string, extra: Record<string, unknown> = {}): Response {
+  return response({ error: message, code: "plan_limit", limit, upgradeUrl: "/billing", ...extra }, 402);
+}
+
+/** Null when allowed; otherwise the response to return. */
+async function decide(env: Env, workspaceId: string, violation: Response | null, label: string): Promise<Response | null> {
+  if (!violation) return null;
+  const mode = await entitlementMode(env, workspaceId);
+  if (mode === "enforce") return violation;
+  if (mode === "shadow") console.warn(`[entitlements] shadow: would block ${label} for ${workspaceId}`);
+  return null;
+}
+
+export async function checkProjectLimit(env: Env, workspaceId: string): Promise<Response | null> {
+  const { projects } = await getEntitlements(env, workspaceId);
+  if (projects === null) return null;
+  const row = await env.DB.prepare("SELECT COUNT(*) AS count FROM projects WHERE workspace_id = ? AND deleted_at IS NULL")
+    .bind(workspaceId).first<{ count: number }>();
+  const violation = (row?.count ?? 0) >= projects
+    ? planLimit(`Your plan includes ${projects} project${projects === 1 ? "" : "s"}. Upgrade to add more.`, "projects", { included: projects })
+    : null;
+  return decide(env, workspaceId, violation, "project creation");
+}
+
+export type ExecutionMode = "self" | "cloud";
+
+export function executionModeOf(value: unknown): ExecutionMode | null {
+  if (value === undefined || value === null || value === "self") return "self";
+  return value === "cloud" ? "cloud" : null;
+}
+
+/**
+ * Runs on the customer's own machines and CI are never metered or capped.
+ * A cloud run needs the cloud-runner rollout and minutes (or budget) left.
+ */
+export async function checkCloudRun(env: Env, workspaceId: string): Promise<Response | null> {
+  if (!(await flagOn(env, workspaceId, "cloud_runners"))) {
+    return response({ error: "Bugmole Cloud runs aren't available for this workspace yet. Run on your own machine or CI.", code: "cloud_unavailable" }, 422);
+  }
+  const decision = await canSpend(env, workspaceId, "browser_minute", 1);
+  const violation = decision.allowed
+    ? null
+    : planLimit(decision.message, decision.reason === "spending_limit" ? "spending_limit" : decision.reason === "suspended" ? "payment" : "cloud_minutes");
+  return decide(env, workspaceId, violation, "cloud run");
+}
+
+export async function historyCutoffFor(env: Env, workspaceId: string | null, now = new Date()): Promise<string | null> {
+  if (!workspaceId || (await entitlementMode(env, workspaceId)) !== "enforce") return null;
+  const { historyDays } = await getEntitlements(env, workspaceId);
+  return historyDays === null ? null : new Date(now.getTime() - historyDays * 86_400_000).toISOString();
+}

package/src/registry-worker/billing/entitlements.ts

@@ -0,0 +1,108 @@
+// What a workspace's plan allows right now, from workspace_plans plus the
+// shared catalog. No row means Free.
+import {
+  type BillingInterval,
+  type Entitlements,
+  type PlanId,
+  type PlanOverrides,
+  entitlementsFor,
+  isPlanId,
+} from "../../billing/plan-catalog.js";
+import type { Env } from "../core.js";
+
+export type PlanStatus = "active" | "past_due" | "grace" | "canceled";
+
+export type WorkspacePlan = {
+  workspaceId: string;
+  plan: PlanId;
+  interval: BillingInterval | null;
+  status: PlanStatus;
+  periodStart: string | null;
+  periodEnd: string | null;
+  spendingLimitCents: number | null;
+  overrides: PlanOverrides;
+  provider: string | null;
+  providerSubscriptionId: string | null;
+  pendingPlan: PlanId | null;
+  graceUntil: string | null;
+};
+
+type PlanRow = {
+  plan: string;
+  billing_interval: string | null;
+  status: string;
+  current_period_start: string | null;
+  current_period_end: string | null;
+  spending_limit_cents: number | null;
+  overrides_json: string | null;
+  provider: string | null;
+  provider_subscription_id: string | null;
+  pending_plan: string | null;
+  grace_until: string | null;
+};
+
+export function freePlan(workspaceId: string): WorkspacePlan {
+  return {
+    workspaceId,
+    plan: "free",
+    interval: null,
+    status: "active",
+    periodStart: null,
+    periodEnd: null,
+    spendingLimitCents: null,
+    overrides: {},
+    provider: null,
+    providerSubscriptionId: null,
+    pendingPlan: null,
+    graceUntil: null,
+  };
+}
+
+export async function getWorkspacePlan(env: Env, workspaceId: string): Promise<WorkspacePlan> {
+  const row = await env.DB.prepare("SELECT * FROM workspace_plans WHERE workspace_id = ?")
+    .bind(workspaceId).first<PlanRow>();
+  if (!row || !isPlanId(row.plan)) return freePlan(workspaceId);
+  const status = (["active", "past_due", "grace", "canceled"] as const).find((value) => value === row.status) ?? "active";
+  // A canceled paid plan behaves like Free until someone subscribes again.
+  if (status === "canceled") return { ...freePlan(workspaceId), spendingLimitCents: row.spending_limit_cents };
+  let overrides: PlanOverrides = {};
+  try {
+    overrides = row.overrides_json ? JSON.parse(row.overrides_json) as PlanOverrides : {};
+  } catch {
+    overrides = {};
+  }
+  return {
+    workspaceId,
+    plan: row.plan,
+    interval: row.billing_interval === "month" || row.billing_interval === "year" ? row.billing_interval : null,
+    status,
+    periodStart: row.current_period_start,
+    periodEnd: row.current_period_end,
+    spendingLimitCents: row.spending_limit_cents,
+    overrides,
+    provider: row.provider,
+    providerSubscriptionId: row.provider_subscription_id,
+    pendingPlan: isPlanId(row.pending_plan) ? row.pending_plan : null,
+    graceUntil: row.grace_until,
+  };
+}
+
+export async function getEntitlements(env: Env, workspaceId: string): Promise<Entitlements & { plan: WorkspacePlan }> {
+  const plan = await getWorkspacePlan(env, workspaceId);
+  return { ...entitlementsFor(plan.plan, plan.overrides), plan };
+}
+
+/**
+ * Cloud usage stops once a failed payment has run past its grace period.
+ * Local and CI runs are never affected.
+ */
+export function cloudUsageSuspended(plan: WorkspacePlan, now = new Date()): boolean {
+  if (plan.status === "grace") return true;
+  return plan.status === "past_due" && Boolean(plan.graceUntil) && Date.parse(plan.graceUntil!) <= now.getTime();
+}
+
+export async function workspaceOfProject(env: Env, projectId: string): Promise<string | null> {
+  const row = await env.DB.prepare("SELECT workspace_id AS workspaceId FROM projects WHERE id = ?")
+    .bind(projectId).first<{ workspaceId: string | null }>();
+  return row?.workspaceId ?? null;
+}