@bugmole/cli 0.4.0

package/src/runtime/reviewer.ts

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+
+interface ReviewOptions {
+  filePath: string;
+  changeSummary: string;
+  diff: string;
+  evidence: any;
+}
+
+interface ReviewResult {
+  status: "success" | "error";
+  verdict?: "APPROVED" | "REJECTED" | "REQUIRE_CLARIFICATION";
+  reasoning?: string;
+  riskAssessment?: {
+    level: "low" | "medium" | "high";
+    failureModes?: string[];
+    couldMaskDefect?: boolean;
+  };
+  conditions?: string[];
+  message?: string;
+  error?: string;
+}
+
+/**
+ * Collects every string leaf value out of an arbitrarily-shaped evidence
+ * object. Callers pass evidence as free-form JSON (trace/video/screenshot/
+ * network-receipt references per docs/governor-policy.md §2); this makes no
+ * assumption about its exact keys, only that a real reference is a string.
+ */
+function collectEvidenceStrings(value: unknown, out: string[] = []): string[] {
+  if (typeof value === "string") {
+    if (value.trim()) out.push(value.trim());
+  } else if (Array.isArray(value)) {
+    for (const item of value) collectEvidenceStrings(item, out);
+  } else if (value && typeof value === "object") {
+    for (const item of Object.values(value)) collectEvidenceStrings(item, out);
+  }
+  return out;
+}
+
+/**
+ * A referenced evidence string is verifiable if it resolves to a real file,
+ * either as an absolute path or relative to the run's artifacts directory.
+ * Non-path strings (e.g. a short free-text note) never verify, by design:
+ * per docs/governor-policy.md §6, a proof token must be evidence, not prose.
+ */
+function evidenceStringExists(reference: string, artifactsDir: string): boolean {
+  const candidates = path.isAbsolute(reference)
+    ? [reference]
+    : [path.join(artifactsDir, reference), path.resolve(reference)];
+  return candidates.some((candidate) => {
+    try {
+      return fs.statSync(candidate).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Reviewer: Validates proposed changes for safety and correctness.
+ *
+ * This is the anti-"false green" gate from docs/governor-policy.md §6: a
+ * change is never APPROVED on the strength of a non-empty `evidence` object
+ * alone — at least one referenced artifact must actually exist on disk.
+ */
+export async function review(cfg: any, options: ReviewOptions): Promise<ReviewResult> {
+  try {
+    const { filePath, changeSummary, diff, evidence } = options;
+    const specDir = cfg.runtime.spec_dir || "./spec";
+    const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
+    const fullPath = path.join(specDir, filePath);
+
+    if (!fs.existsSync(fullPath)) {
+      return {
+        status: "error",
+        error: `File not found: ${filePath}`,
+      };
+    }
+
+    // Loaded to confirm the target file is readable at review time; the
+    // content itself is not otherwise inspected here.
+    fs.readFileSync(fullPath, "utf-8");
+
+    let verdict: "APPROVED" | "REJECTED" | "REQUIRE_CLARIFICATION" = "REQUIRE_CLARIFICATION";
+    let riskLevel: "low" | "medium" | "high" = "medium";
+
+    const evidenceReferences = collectEvidenceStrings(evidence);
+    const verifiedEvidence = evidenceReferences.filter((reference) => evidenceStringExists(reference, artifactsDir));
+
+    const checks = {
+      evidenceReferenced: evidenceReferences.length > 0,
+      hasVerifiedEvidence: verifiedEvidence.length > 0,
+      hasDiff: !!diff && diff.length > 10,
+      hasSummary: !!changeSummary && changeSummary.length > 10,
+      diffReducesProofs: diff.includes("proofs:") && /proofs:\s*\[\s*\]/.test(diff),
+      diffRemovesJourney: diff.includes("- id:") && diff.includes("journey"),
+    };
+
+    if (!checks.hasVerifiedEvidence || !checks.hasDiff || !checks.hasSummary) {
+      verdict = "REQUIRE_CLARIFICATION";
+      riskLevel = "high";
+    } else if (checks.diffReducesProofs || checks.diffRemovesJourney) {
+      verdict = "REJECTED";
+      riskLevel = "high";
+    } else {
+      verdict = "APPROVED";
+      riskLevel = "low";
+    }
+
+    const evidenceNote = !checks.evidenceReferenced
+      ? "no evidence referenced"
+      : checks.hasVerifiedEvidence
+        ? `${verifiedEvidence.length}/${evidenceReferences.length} referenced artifacts verified on disk`
+        : `${evidenceReferences.length} referenced artifact(s), none found on disk`;
+    const reasoning = `Review based on verified evidence presence, diff quality, and safety checks. Evidence: ${evidenceNote}. Diff quality: ${checks.hasDiff}, Summary: ${checks.hasSummary}.`;
+
+    const riskAssessment = {
+      level: riskLevel,
+      failureModes: [
+        ...(checks.diffReducesProofs ? ["Proof requirements reduced"] : []),
+        ...(checks.diffRemovesJourney ? ["Journey removed"] : []),
+        ...(!checks.hasVerifiedEvidence ? ["No independently verifiable evidence"] : []),
+      ],
+      couldMaskDefect: checks.diffReducesProofs || checks.diffRemovesJourney || !checks.hasVerifiedEvidence,
+    };
+
+    const conditions: string[] = [];
+    if (verdict === "APPROVED") {
+      conditions.push("Safe to auto-apply if risk is low and change type is auto-learnable");
+    } else if (verdict === "REQUIRE_CLARIFICATION") {
+      conditions.push(
+        checks.hasVerifiedEvidence
+          ? "Missing or insufficient evidence"
+          : "Referenced evidence could not be verified on disk",
+      );
+      conditions.push("Diff quality needs improvement");
+    } else {
+      conditions.push("Change reduces coverage or weakens proofs");
+      conditions.push("Requires human approval");
+    }
+
+    return {
+      status: "success",
+      verdict,
+      reasoning,
+      riskAssessment,
+      conditions,
+      message: `Review completed. Verdict: ${verdict}`,
+    };
+  } catch (error: any) {
+    return {
+      status: "error",
+      error: error.message || "Review failed",
+    };
+  }
+}

package/src/runtime/run-job.ts

@@ -0,0 +1,136 @@
+// Executes one claimed registry run and reports it: heartbeats while it runs,
+// then the final result. Shared by `bugmole serve` (the customer's own worker)
+// and `bugmole run-once` (a Bugmole Cloud runner).
+import type { ControlPlaneClient, RegistryRun } from "../registry/control-plane-client.js";
+import { runKey } from "../storage/keys.js";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { normalizeTargets } from "./browser-matrix.js";
+import { execute } from "./executor.js";
+import type { FailureAnalysis, FailureContext } from "./failure-analysis.js";
+import { loadDeviceCloudAccess, type DeviceCloudAccess } from "./device-clouds/index.js";
+
+/** The registry expires a claim 60s after its last update, so a running run renews it well inside that. */
+export const RUN_HEARTBEAT_MS = 30_000;
+
+/** The registry asked the worker to stop (usage cap, time limit). */
+export type StopSignal = { reason: string; message: string };
+
+export type ExecuteResult = Awaited<ReturnType<typeof execute>>;
+
+/**
+ * The fix an earlier failed run suggested, read from that run's stored
+ * analysis. A missing or fix-less analysis applies nothing, so the run
+ * reports it rather than silently re-running the old flow.
+ */
+export async function loadSuggestedFix(cfg: any, projectId: string, fixFrom: { runId: string; targetId: string; mode?: "suggested" | "ai" }) {
+  const store = createProjectObjectStore(cfg);
+  const base = { sourceRunId: fixFrom.runId, targetId: fixFrom.targetId, mode: fixFrom.mode ?? "suggested" } as const;
+  const read = async <T>(name: string): Promise<T | undefined> => {
+    try {
+      return JSON.parse(await store.getText(runKey(projectId, fixFrom.runId, `artifacts/${fixFrom.targetId}/${name}`))) as T;
+    } catch {
+      return undefined;
+    }
+  };
+  const analysis = await read<FailureAnalysis>("analysis.json");
+  if (base.mode !== "ai") return { ...base, changes: analysis?.suggestedFix?.changes ?? [] };
+  const failureContext = await read<FailureContext>("failure-context.json");
+  return { ...base, changes: [], ...(analysis ? { analysis } : {}), ...(failureContext ? { failureContext } : {}) };
+}
+
+function stopSignalOf(reply: unknown): StopSignal | null {
+  const body = reply as { stop?: unknown; reason?: unknown; message?: unknown } | null;
+  if (!body || body.stop !== true) return null;
+  return {
+    reason: typeof body.reason === "string" ? body.reason : "stopped",
+    message: typeof body.message === "string" ? body.message : "The registry stopped this run.",
+  };
+}
+
+export type ExecuteRunOptions = {
+  projectId: string;
+  workerId: string;
+  /** Called once if the registry answers an update with `stop`. */
+  onStop?: (signal: StopSignal) => void;
+  execute?: typeof execute;
+  heartbeatMs?: number;
+  /** Loads device-cloud credentials and app builds, for runs that target cloud devices. */
+  loadDeviceAccess?: () => Promise<DeviceCloudAccess>;
+};
+
+/** How a worker fetches a run's device access from the registry. */
+export function registryDeviceAccess(cfg: any, registryUrl: string, token: string, projectId: string, runId: string): () => Promise<DeviceCloudAccess> {
+  return () => loadDeviceCloudAccess({
+    registryUrl,
+    token,
+    runId,
+    loadObject: (key) => createProjectObjectStore({ ...cfg, project: { ...(cfg.project ?? {}), id: projectId } }).get(key),
+  });
+}
+
+/** Runs a run this worker already holds and reports its result. Throws if execution itself fails. */
+export async function executeRegistryRun(
+  cfg: any,
+  client: Pick<ControlPlaneClient, "updateRun">,
+  run: RegistryRun,
+  options: ExecuteRunOptions,
+): Promise<ExecuteResult> {
+  const { workerId } = options;
+  let stopped = false;
+  const report = async (update: Record<string, unknown>) => {
+    const reply = await client.updateRun(run.id, update);
+    const signal = stopSignalOf(reply);
+    if (signal && !stopped) {
+      stopped = true;
+      options.onStop?.(signal);
+    }
+  };
+  // An update overwrites the run's step counts, so a heartbeat resends the latest progress.
+  let lastProgress: Record<string, unknown> = {};
+  const heartbeat = setInterval(() => {
+    void report({ workerId, status: "running", eventType: "heartbeat", ...lastProgress }).catch(() => undefined);
+  }, options.heartbeatMs ?? RUN_HEARTBEAT_MS);
+  heartbeat.unref?.();
+  try {
+    // A malformed matrix is a request problem, not a reason to run a
+    // different set of browsers than the person asked for.
+    const targets = normalizeTargets(run.targets ?? undefined);
+    const applyFix = run.fixFrom ? await loadSuggestedFix(cfg, options.projectId, run.fixFrom) : undefined;
+    const deviceClouds = targets.some((target) => target.cloud) && options.loadDeviceAccess ? await options.loadDeviceAccess() : undefined;
+    const result = await (options.execute ?? execute)(cfg, {
+      ...(applyFix ? { applyFix } : {}),
+      ...(deviceClouds ? { deviceClouds } : {}),
+      planId: run.planId,
+      journeyId: run.journeyId,
+      runId: run.id,
+      baseUrl: run.environmentBaseUrl || undefined,
+      targets: targets.length > 0 ? targets : undefined,
+      onProgress: async (progress) => {
+        // Step-level updates don't carry the matrix; keep the last known one.
+        lastProgress = { ...lastProgress, ...progress };
+        await report({ workerId, status: "running", eventType: "progress", ...lastProgress });
+      },
+    });
+    clearInterval(heartbeat);
+    await client.updateRun(run.id, {
+      workerId,
+      status: result.status === "success" ? "success" : result.status === "partial" ? "partial" : "error",
+      eventType: "completed",
+      stepsExecuted: result.stepsExecuted,
+      stepsPassed: result.stepsPassed,
+      stepsFailed: result.stepsFailed,
+      driver: result.driver,
+      platform: result.platform,
+      recoveryAttempts: result.recoveryAttempts,
+      failureCode: result.failureCode,
+      artifactSummaryJson: result.manifestKey ? JSON.stringify({ manifest: result.manifestKey }) : undefined,
+      manifestKey: result.manifestKey,
+      errorMessage: result.error,
+      targetResults: result.targetResults,
+      durationMs: result.durationMs,
+    });
+    return result;
+  } finally {
+    clearInterval(heartbeat);
+  }
+}

package/src/runtime/run-once.test.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import worker from "../registry-worker/index.js";
+import { call, createContext, createTestEnv, seedPlan, seedProject, seedVerifiedDomain } from "../registry-worker/testing/harness.js";
+import { runnerLauncher, type LaunchRequest } from "../registry-worker/runner/dispatch.js";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { RegistryObjectStore } from "../storage/registry-object-store.js";
+import { parseArgs, resolveMode } from "../../scripts/bugmole.js";
+import { cloudRunConfig, runOnce } from "./run-once.js";
+import type { execute } from "./executor.js";
+
+type Execute = typeof execute;
+type Result = Awaited<ReturnType<Execute>>;
+
+/** Sends every fetch to the in-process registry. */
+function registryFetch(env: ReturnType<typeof createTestEnv>["env"]): typeof fetch {
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const { ctx, flush } = createContext();
+    const reply = await worker.fetch(new Request(input, init), env, ctx);
+    await flush();
+    return reply;
+  }) as typeof fetch;
+}
+
+function withEnv<T>(values: Record<string, string>, body: () => Promise<T>): Promise<T> {
+  const saved = Object.fromEntries(Object.keys(values).map((key) => [key, process.env[key]]));
+  Object.assign(process.env, values);
+  return body().finally(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+}
+
+async function queuedCloudRun() {
+  const setup = createTestEnv({ RUNNER_TOKEN_SECRET: "s", FEATURE_CLOUD_RUNNERS: "on" });
+  const { env, artifacts, db } = setup;
+  const project = await seedProject(env, { storageProvider: "bugmole" });
+  await seedPlan(env, project.projectId, project.owner);
+  await artifacts.put(`projects/${project.projectId}/plans/checkout.flow.yaml`, "suites: []\n");
+  // The discovery test below explores https://shop.test.
+  seedVerifiedDomain(db, project.workspaceId, "shop.test");
+  const launches: LaunchRequest[] = [];
+  const original = runnerLauncher.start;
+  runnerLauncher.start = async (_env, launch) => {
+    launches.push(launch);
+  };
+  try {
+    const created = await call(env, "POST", `/api/projects/${project.projectId}/runs`, {
+      as: project.owner,
+      body: { planId: "checkout", idempotencyKey: "k", executionMode: "cloud", targets: [{ browser: "firefox" }] },
+    });
+    assert.equal(created.status, 201);
+  } finally {
+    runnerLauncher.start = original;
+  }
+  return { ...setup, ...project, launch: launches[0] };
+}
+
+test("bugmole run-once is its own command", () => {
+  assert.equal(resolveMode(parseArgs(["node", "bugmole", "run-once"])), "run-once");
+});
+
+test("a cloud runner executes its run with Bugmole storage and reports back", async () => {
+  const { env, artifacts, owner, projectId, launch } = await queuedCloudRun();
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = registryFetch(env);
+  const seen: Array<{ plan: string; targets: unknown }> = [];
+  const fakeExecute = (async (cfg: any, options: any): Promise<Result> => {
+    const store = createProjectObjectStore(cfg);
+    seen.push({ plan: await store.getText(`projects/${projectId}/plans/checkout.flow.yaml`), targets: options.targets });
+    const manifestKey = `projects/${projectId}/runs/${options.runId}/manifest.json`;
+    await store.put(manifestKey, "{}", "application/json");
+    await options.onProgress({ stepsExecuted: 1 });
+    return { status: "success", stepsExecuted: 1, stepsPassed: 1, stepsFailed: 0, manifestKey, durationMs: 10 } as unknown as Result;
+  }) as Execute;
+  try {
+    const code = await withEnv({ BUGMOLE_REGISTRY_URL: launch.registryUrl, BUGMOLE_RUN_ID: launch.id, BUGMOLE_RUN_TOKEN: launch.token }, () =>
+      runOnce(process.env, { execute: fakeExecute, log: () => undefined }));
+    assert.equal(code, 0);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+  assert.equal(seen[0].plan, "suites: []\n");
+  assert.deepEqual(seen[0].targets, [{ id: "firefox", browser: "firefox" }]);
+  const run = await call(env, "GET", `/api/runs/${launch.id}`, { as: owner });
+  assert.equal(run.json.run.status, "success");
+  assert.equal(run.json.run.manifestKey, `projects/${projectId}/runs/${launch.id}/manifest.json`);
+  assert.equal(run.json.run.billedMinutes, 1);
+  assert.ok(artifacts.objects.has(run.json.run.manifestKey));
+});
+
+test("a runner stops when the registry says so, and a crash is reported", async () => {
+  const updates: Array<Record<string, unknown>> = [];
+  const bundle = {
+    run: { id: "run_1", projectId: "shop", planId: "checkout", status: "running" },
+    project: { id: "shop" },
+    workerId: "cloud:run_1",
+  };
+  const fetchBundle = (async () => Response.json(bundle)) as unknown as typeof fetch;
+  const client = {
+    async updateRun(_id: string, update: Record<string, unknown>) {
+      updates.push(update);
+      return update.eventType === "progress" ? { updated: true, stop: true, reason: "quota", message: "Minutes are used up." } : { updated: true };
+    },
+    async updateTask() {
+      return { updated: true };
+    },
+    async publishPlan() {
+      return { plan: {} };
+    },
+    async claimTask() {
+      return { claimed: true };
+    },
+  };
+  const env = { BUGMOLE_REGISTRY_URL: "https://r", BUGMOLE_RUN_ID: "run_1", BUGMOLE_RUN_TOKEN: "vrt_x" };
+  const hangs = (async (_cfg: unknown, options: any) => {
+    await options.onProgress({ stepsExecuted: 1 });
+    return new Promise<Result>(() => undefined);
+  }) as Execute;
+  assert.equal(await runOnce(env, { fetch: fetchBundle, client: client as never, execute: hangs, log: () => undefined }), 0);
+  assert.deepEqual(updates.at(-1), { workerId: "cloud:run_1", status: "error", eventType: "stopped", failureCode: "usage_limit", errorMessage: "Minutes are used up." });
+
+  const crashes = (async () => {
+    throw new Error("browser crashed");
+  }) as Execute;
+  assert.equal(await runOnce(env, { fetch: fetchBundle, client: client as never, execute: crashes, log: () => undefined }), 1);
+  assert.equal(updates.at(-1)?.errorMessage, "browser crashed");
+
+  assert.equal(await runOnce({}, { log: () => undefined }), 2, "missing run settings");
+  const refused = (async () => new Response("{}", { status: 409 })) as unknown as typeof fetch;
+  assert.equal(await runOnce(env, { fetch: refused, log: () => undefined }), 1);
+});
+
+test("a cloud runner explores a site, publishes the flows, and keeps the stored journey graph", async () => {
+  const { env, artifacts, owner, projectId } = await queuedCloudRun();
+  await artifacts.put(`projects/${projectId}/journeys/graph.json`, JSON.stringify({
+    version: 1, projectId, journeys: [], edges: [],
+    nodes: [{ id: "screen:/pricing", kind: "screen", title: "Pricing", route: "/pricing" }],
+  }));
+  const launches: LaunchRequest[] = [];
+  const original = runnerLauncher.start;
+  runnerLauncher.start = async (_env, launch) => {
+    launches.push(launch);
+  };
+  let taskId = "";
+  try {
+    const created = await call(env, "POST", `/api/projects/${projectId}/tasks`, {
+      as: owner, body: { title: "Explore https://shop.test", description: "Explore https://shop.test/", taskType: "discovery", idempotencyKey: "d", executionMode: "cloud" },
+    });
+    taskId = created.json.task.id;
+  } finally {
+    runnerLauncher.start = original;
+  }
+  const launch = launches.find((item) => item.kind === "task")!;
+  const discover = (async (url: string) => ({
+    baseUrl: url,
+    events: [{ at: new Date().toISOString(), kind: "page", text: "Opened /" }],
+    pages: [{ route: "/", title: "Shop", path: [], links: [], forms: [] }],
+    flows: [{ id: "discovered-home", name: "Open the shop", kind: "page", route: "/", steps: ["Open the shop"], file: "flows/discovered/home.yaml", content: "url: https://shop.test/\n---\n- launchApp\n" }],
+  })) as never;
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = registryFetch(env);
+  try {
+    const code = await withEnv({ BUGMOLE_REGISTRY_URL: launch.registryUrl, BUGMOLE_TASK_ID: launch.id, BUGMOLE_RUN_TOKEN: launch.token }, () =>
+      runOnce({ ...process.env, BUGMOLE_RUN_ID: "" }, { discover, log: () => undefined }));
+    assert.equal(code, 0);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+  const tasks = await call(env, "GET", `/api/projects/${projectId}/tasks`, { as: owner });
+  const task = tasks.json.tasks.find((item: { id: string }) => item.id === taskId);
+  assert.equal(task.status, "completed");
+  assert.equal(task.billedMinutes, 1);
+  const plans = await call(env, "GET", `/api/projects/${projectId}/plans`, { as: owner });
+  assert.ok(plans.json.plans.some((plan: { planId: string }) => plan.planId === "discovered-home"));
+  assert.ok(artifacts.objects.has(`projects/${projectId}/spec/flows/discovered/home.yaml`));
+  assert.ok(artifacts.objects.has(`projects/${projectId}/plans/discovered-home.flow.yaml`));
+  const graph = JSON.parse(await (await artifacts.get(`projects/${projectId}/journeys/graph.json`))!.text());
+  const routes = graph.nodes.map((node: { route: string }) => node.route).sort();
+  assert.deepEqual(routes, ["/", "/pricing"], "the earlier graph is kept");
+});
+
+test("Bugmole storage lists and deletes through the registry", async () => {
+  const { env, owner, projectId } = await queuedCloudRun();
+  const key = await call(env, "POST", "/api/api-keys", { as: owner, body: { name: "cli", projectIds: [projectId], scopes: ["runs:write", "projects:read"] } });
+  assert.equal(key.status, 201, JSON.stringify(key.json));
+  const store = new RegistryObjectStore({ registryUrl: "https://registry.test", token: key.json.token, projectId, fetch: registryFetch(env) });
+  await store.put(`projects/${projectId}/spec/flows/a.yaml`, "- launchApp\n", "text/yaml");
+  await store.put(`projects/${projectId}/spec/flows/b.yaml`, "- launchApp\n", "text/yaml");
+  assert.equal(await store.has(`projects/${projectId}/spec/flows/a.yaml`), true);
+  assert.equal(await store.has(`projects/${projectId}/spec/flows/missing.yaml`), false);
+  assert.deepEqual((await store.list(`projects/${projectId}/spec/`)).map((item) => item.key).sort(), [
+    `projects/${projectId}/spec/flows/a.yaml`,
+    `projects/${projectId}/spec/flows/b.yaml`,
+  ]);
+  await store.deletePrefix(`projects/${projectId}/spec`);
+  assert.deepEqual(await store.list(`projects/${projectId}/spec/`), []);
+  await assert.rejects(store.get(`projects/${projectId}/spec/flows/a.yaml`), /404/);
+  await assert.rejects(store.put("projects/other/x.yaml", "x"), /400|403/);
+
+  const cfg = cloudRunConfig({ project: { id: projectId }, workerId: "w" }, "/tmp/x", "https://registry.test");
+  await withEnv({ BUGMOLE_RUN_TOKEN: "vrt_token" }, async () => {
+    assert.equal(createProjectObjectStore(cfg).provider, "bugmole");
+  });
+});

package/src/runtime/run-once.ts

@@ -0,0 +1,168 @@
+// `bugmole run-once`: what a Bugmole Cloud container runs. It starts clean,
+// fetches its job (a test run or a discovery task) from the registry with the
+// token it was given, executes it against Bugmole storage, reports, and
+// exits. The container stops with it.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ControlPlaneClient, type RegistryRun, type RegistryTask } from "../registry/control-plane-client.js";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import { executeRegistryRun, registryDeviceAccess, type StopSignal } from "./run-job.js";
+import { runDiscoveryTask } from "./discovery-task.js";
+import type { execute } from "./executor.js";
+import type { discoverSite } from "./site-discovery.js";
+
+type JobBundle = {
+  project: { id: string; name?: string; workspaceId?: string | null };
+  workerId: string;
+  maxMinutes?: number;
+};
+export type RunBundle = JobBundle & { run: RegistryRun };
+export type TaskBundle = JobBundle & { task: RegistryTask };
+
+type Env = Record<string, string | undefined>;
+
+type RunnerClient = Pick<ControlPlaneClient, "updateRun" | "updateTask" | "publishPlan" | "claimTask">;
+
+export type RunOnceDeps = {
+  fetch?: typeof fetch;
+  execute?: typeof execute;
+  discover?: typeof discoverSite;
+  client?: RunnerClient;
+  log?: (message: string) => void;
+};
+
+/** The config cloud work executes with: web, headless, Bugmole storage, no local spec. */
+export function cloudRunConfig(bundle: JobBundle, workdir: string, registryUrl: string) {
+  return {
+    version: 1,
+    project: {
+      id: bundle.project.id,
+      name: bundle.project.name ?? bundle.project.id,
+      workspace_id: bundle.project.workspaceId ?? undefined,
+      platform: "web",
+    },
+    runtime: {
+      artifacts_dir: path.join(workdir, "runs"),
+      spec_dir: path.join(workdir, "spec"),
+    },
+    execution: {
+      driver: "playwright",
+      playwright: { headless: true },
+    },
+    storage: {
+      provider: "bugmole",
+      bugmole: { registry_url: registryUrl },
+    },
+  };
+}
+
+const FAILURE_CODES: Record<string, string> = {
+  time_limit: "time_limit",
+  quota: "usage_limit",
+  spending_limit: "usage_limit",
+  suspended: "usage_limit",
+};
+
+/**
+ * Discovery adds to the project's journey graph, which a clean container
+ * doesn't have on disk; start from the stored one so nothing is lost.
+ */
+async function restoreJourneyGraph(cfg: ReturnType<typeof cloudRunConfig>): Promise<void> {
+  const store = createProjectObjectStore(cfg);
+  const key = `${projectPrefix(cfg.project.id)}/journeys/graph.json`;
+  if (!(await store.has(key))) return;
+  const file = path.join(cfg.runtime.spec_dir, "journeys.graph.json");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, await store.getText(key), "utf8");
+}
+
+/** Returns the process exit code. */
+export async function runOnce(env: Env = process.env, deps: RunOnceDeps = {}): Promise<number> {
+  const log = deps.log ?? ((message: string) => console.log(`[Bugmole] ${message}`));
+  const registryUrl = env.BUGMOLE_REGISTRY_URL?.trim().replace(/\/$/, "");
+  const runId = env.BUGMOLE_RUN_ID?.trim();
+  const taskId = env.BUGMOLE_TASK_ID?.trim();
+  const token = env.BUGMOLE_RUN_TOKEN?.trim();
+  const job = runId ? { kind: "run" as const, id: runId } : taskId ? { kind: "task" as const, id: taskId } : null;
+  if (!registryUrl || !job || !token) {
+    log("run-once needs BUGMOLE_REGISTRY_URL, BUGMOLE_RUN_TOKEN, and BUGMOLE_RUN_ID or BUGMOLE_TASK_ID");
+    return 2;
+  }
+  const doFetch = deps.fetch ?? fetch;
+  const reply = await doFetch(`${registryUrl}/api/runner/${job.kind}s/${encodeURIComponent(job.id)}/bundle`, {
+    headers: { authorization: `Bearer ${token}` },
+  }).catch((error: unknown) => {
+    log(`Couldn't reach the registry: ${error instanceof Error ? error.message : error}`);
+    return null;
+  });
+  if (!reply?.ok) {
+    if (reply) log(`The registry refused ${job.kind} ${job.id} (${reply.status})`);
+    return 1;
+  }
+  const bundle = await reply.json() as RunBundle & TaskBundle;
+  const projectId = bundle.project.id;
+  const workerId = bundle.workerId;
+  const client: RunnerClient = deps.client ?? new ControlPlaneClient({ registryUrl, apiKey: token, projectId });
+  const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "bugmole-run-"));
+  const cfg = cloudRunConfig(bundle, workdir, registryUrl);
+
+  let stop: (signal: StopSignal) => void = () => undefined;
+  const stopped = new Promise<StopSignal>((resolve) => {
+    stop = resolve;
+  });
+  const deadline = bundle.maxMinutes
+    ? setTimeout(() => stop({ reason: "time_limit", message: `Cloud work stops after ${bundle.maxMinutes} minutes.` }), bundle.maxMinutes * 60_000)
+    : undefined;
+  deadline?.unref?.();
+
+  const report = (update: Record<string, unknown>) => job.kind === "run"
+    ? client.updateRun(job.id, update)
+    : client.updateTask(job.id, { workerId, status: update.status, errorMessage: update.errorMessage, progressMessage: update.errorMessage });
+
+  try {
+    let work: Promise<string>;
+    if (job.kind === "run") {
+      log(`Running ${bundle.run.planId} for ${projectId} (${job.id})`);
+      work = executeRegistryRun(cfg, client, bundle.run, {
+        projectId,
+        workerId,
+        onStop: stop,
+        execute: deps.execute,
+        loadDeviceAccess: registryDeviceAccess(cfg, registryUrl, token, projectId, job.id),
+      })
+        .then((result) => result.status);
+    } else {
+      log(`Exploring for ${projectId} (${job.id})`);
+      await restoreJourneyGraph(cfg);
+      work = runDiscoveryTask(cfg, client, bundle.task, workerId, deps.discover, { claimed: true, onStop: stop })
+        .then(() => "done");
+    }
+    const outcome = await Promise.race([
+      work.then((status) => ({ status })),
+      stopped.then((signal) => ({ signal })),
+    ]);
+    if ("signal" in outcome) {
+      log(`Stopped: ${outcome.signal.message}`);
+      await report({
+        workerId,
+        status: "error",
+        eventType: "stopped",
+        failureCode: FAILURE_CODES[outcome.signal.reason] ?? "stopped",
+        errorMessage: outcome.signal.message,
+      }).catch(() => undefined);
+      return 0;
+    }
+    log(`Finished: ${outcome.status}`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Cloud work failed";
+    log(`Failed: ${message}`);
+    await report({ workerId, status: "error", eventType: "failed", errorMessage: message }).catch(() => undefined);
+    return 1;
+  } finally {
+    if (deadline) clearTimeout(deadline);
+    fs.rmSync(workdir, { recursive: true, force: true });
+  }
+}