@bugmole/cli 0.4.0 → 0.5.0

package/LICENSE

@@ -1,7 +1,21 @@
+MIT License
+
 Copyright (c) 2026 The AI, Inc.
 
-All rights reserved.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-This software and its source code are proprietary and confidential. No license
-or right to use, copy, modify, distribute, sublicense, or sell this software
-is granted without prior written permission from The AI, Inc.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bugmole/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -27,7 +27,7 @@
     "bm": "scripts/bugmole.cjs"
   },
   "scripts": {
-    "postinstall": "node scripts/ensure-maestro.cjs",
+    "postinstall": "node scripts/ensure-maestro.cjs && node scripts/ensure-playwright.cjs",
     "bugmole:mcp": "NODE_OPTIONS=--max-old-space-size=512 tsx --no-cache scripts/bugmole.ts --mcp",
     "bugmole:explore": "NODE_OPTIONS=--max-old-space-size=512 tsx scripts/bugmole.ts --mode explore",
     "bugmole:plan": "NODE_OPTIONS=--max-old-space-size=512 tsx scripts/bugmole.ts --mode plan",
@@ -46,7 +46,7 @@
     "runner:dev": "wrangler dev -c wrangler.runner.jsonc",
     "runner:deploy": "wrangler deploy -c wrangler.runner.jsonc",
     "sync:catalog": "node scripts/sync-plan-catalog.mjs",
-    "test": "NODE_OPTIONS=--max-old-space-size=512 tsx --test --test-concurrency=1 scripts/bugmole.test.ts src/mcp/server.test.ts projects/registry.test.ts src/integrations/testflight-feedback.test.ts src/integrations/temp-email.test.ts src/storage/object-store.test.ts src/storage/local-artifact-server.test.ts src/storage/storage-directory.test.ts src/runtime/reset.test.ts src/runtime/serve-gateway.test.ts src/registry/task-scheduling.test.ts src/registry-worker/artifacts.test.ts src/registry-worker/runs.test.ts src/registry-worker/org/routes.test.ts src/registry-worker/billing/billing-core.test.ts src/registry-worker/billing/paypal.test.ts src/registry-worker/ai/routes.test.ts src/registry-worker/runner/runner.test.ts src/registry-worker/signup/signup.test.ts src/registry-worker/notifications/notifications.test.ts src/registry-worker/github/checks.test.ts src/registry-worker/gitlab/checks.test.ts src/registry-worker/personas/personas.test.ts src/registry-worker/feedback/feedback.test.ts src/registry-worker/devices/devices.test.ts src/registry-worker/domains/domains.test.ts src/registry-worker/sso/sso.test.ts src/registry-worker/mcp/mcp.test.ts src/integrations/github-app.test.ts src/runtime/run-once.test.ts src/runtime/appium-driver.test.ts src/integrations/aws-sigv4.test.ts src/runtime/ai-work.test.ts src/billing/plan-catalog.test.ts src/mcp/write-test-cases.test.ts src/runtime/pipeline.test.ts src/runtime/planner.test.ts src/runtime/test-case-verdicts.test.ts src/runtime/journey-graph.test.ts src/runtime/journey-evidence.test.ts src/runtime/local-browser.test.ts src/runtime/serve-worker.test.ts src/runtime/cursor-driver-run.test.ts src/runtime/explorer.test.ts src/runtime/nav-crawl.test.ts src/runtime/app-understanding.test.ts src/runtime/environment.test.ts src/runtime/blocker-resolution.test.ts src/runtime/ui-reverse-engineering/coordinator.test.ts src/runtime/maestro-driver.test.ts src/runtime/playwright-driver.test.ts src/runtime/flow-language.test.ts src/runtime/web-suite.test.ts src/runtime/canonical-flow.test.ts src/runtime/executor.test.ts src/runtime/ios-screen-record.test.ts src/runtime/android-screen-record.test.ts src/runtime/reviewer.test.ts src/runtime/reporter.test.ts src/runtime/cursor-cli-driver.test.ts src/runtime/local-registry-stub.test.ts src/runtime/browser-matrix.test.ts src/runtime/browser-matrix.integration.test.ts src/runtime/failure-analysis.test.ts src/runtime/site-discovery.test.ts src/runtime/ai-exploration.test.ts src/runtime/discovery-task.test.ts",
+    "test": "NODE_OPTIONS=--max-old-space-size=512 tsx --test --test-concurrency=1 scripts/bugmole.test.ts scripts/ensure-playwright.test.ts scripts/sync-launcher-version.test.ts src/mcp/server.test.ts projects/registry.test.ts src/integrations/testflight-feedback.test.ts src/integrations/temp-email.test.ts src/storage/object-store.test.ts src/storage/local-artifact-server.test.ts src/storage/storage-directory.test.ts src/runtime/reset.test.ts src/runtime/run-job.test.ts src/runtime/serve-gateway.test.ts src/registry/task-scheduling.test.ts src/registry-worker/artifacts.test.ts src/registry-worker/runs.test.ts src/registry-worker/org/routes.test.ts src/registry-worker/billing/billing-core.test.ts src/registry-worker/billing/paypal.test.ts src/registry-worker/ai/routes.test.ts src/registry-worker/runner/runner.test.ts src/registry-worker/signup/signup.test.ts src/registry-worker/signup/attribution.test.ts src/registry-worker/notifications/notifications.test.ts src/registry-worker/github/checks.test.ts src/registry-worker/gitlab/checks.test.ts src/registry-worker/personas/personas.test.ts src/registry-worker/feedback/feedback.test.ts src/registry-worker/devices/devices.test.ts src/registry-worker/domains/domains.test.ts src/registry-worker/sso/sso.test.ts src/registry-worker/mcp/mcp.test.ts src/integrations/github-app.test.ts src/runtime/run-once.test.ts src/runtime/appium-driver.test.ts src/integrations/aws-sigv4.test.ts src/runtime/ai-work.test.ts src/billing/plan-catalog.test.ts src/mcp/write-test-cases.test.ts src/runtime/pipeline.test.ts src/runtime/planner.test.ts src/runtime/test-case-verdicts.test.ts src/runtime/journey-graph.test.ts src/runtime/journey-evidence.test.ts src/runtime/local-browser.test.ts src/runtime/serve-worker.test.ts src/runtime/cursor-driver-run.test.ts src/runtime/explorer.test.ts src/runtime/nav-crawl.test.ts src/runtime/app-understanding.test.ts src/runtime/environment.test.ts src/runtime/blocker-resolution.test.ts src/runtime/ui-reverse-engineering/coordinator.test.ts src/runtime/maestro-driver.test.ts src/runtime/playwright-driver.test.ts src/runtime/flow-language.test.ts src/runtime/web-suite.test.ts src/runtime/canonical-flow.test.ts src/runtime/executor.test.ts src/runtime/ios-screen-record.test.ts src/runtime/android-screen-record.test.ts src/runtime/reviewer.test.ts src/runtime/reporter.test.ts src/runtime/cursor-cli-driver.test.ts src/runtime/local-registry-stub.test.ts src/runtime/browser-matrix.test.ts src/runtime/browser-matrix.integration.test.ts src/runtime/failure-analysis.test.ts src/runtime/site-discovery.test.ts src/runtime/ai-exploration.test.ts src/runtime/discovery-task.test.ts",
     "test:mcp": "NODE_OPTIONS=--max-old-space-size=512 tsx --test --test-concurrency=1 scripts/bugmole.test.ts src/mcp/server.test.ts projects/registry.test.ts src/integrations/testflight-feedback.test.ts src/storage/object-store.test.ts src/runtime/maestro-driver.test.ts src/runtime/canonical-flow.test.ts",
     "typecheck": "NODE_OPTIONS=--max-old-space-size=512 tsc --noEmit"
   },
@@ -59,7 +59,7 @@
     "automation"
   ],
   "author": "",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1085.0",
     "@aws-sdk/s3-request-presigner": "^3.1085.0",

package/scripts/bugmole.ts

@@ -18,6 +18,7 @@ type Mode =
   | "plan"
   | "run"
   | "propose-diff"
+  | "discover"
   | "review"
   | "report"
   | "artifacts"
@@ -472,6 +473,65 @@ async function main() {
     return;
   }
 
+  // Explores a running app like a first-time visitor and writes a flow for
+  // every page and form it finds, ready for --mode suite. With --sign-in, that
+  // flow runs first and exploration continues in its session, which is
+  // deleted afterwards.
+  if (mode === "discover") {
+    const { discoverSite } = await import("../src/runtime/site-discovery.js");
+    const baseUrl = typeof args.baseurl === "string" ? args.baseurl : process.env.BUGMOLE_BASE_URL;
+    if (!baseUrl) throw new Error("--base-url (or BUGMOLE_BASE_URL) is required for --mode discover");
+    if (typeof args.out !== "string") throw new Error("--out <directory> is required for --mode discover");
+    const outDir = path.resolve(workspaceRoot, args.out);
+    const sessionDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "bugmole-discover-"));
+    try {
+      let storageState: string | undefined;
+      if (typeof args.signin === "string") {
+        const { PlaywrightDriver } = await import("../src/runtime/playwright-driver.js");
+        storageState = path.join(sessionDir, "session-state.json");
+        const signIn = await new PlaywrightDriver({ headless: args.headed !== true }).run({
+          runId: `discover-${Date.now()}`,
+          projectId: typeof args.project === "string" ? args.project : path.basename(workspaceRoot),
+          journeyId: "sign-in",
+          flowPath: path.resolve(workspaceRoot, args.signin),
+          platform: "web",
+          target: { baseUrl },
+          rebaseOrigin: true,
+          timeoutMs: typeof args.timeout === "number" ? args.timeout : 30_000,
+          artifactsDir: path.join(sessionDir, "artifacts"),
+          sessionStatePath: storageState,
+        });
+        if (signIn.status !== "passed") throw new Error(`Sign-in flow did not pass: ${signIn.message}`);
+        console.log(`[Bugmole] Signed in with ${args.signin}`);
+      }
+      const result = await discoverSite(baseUrl, {
+        storageState,
+        openEachPage: args.openeachpage === true,
+        maxPages: typeof args.maxpages === "number" ? args.maxpages : undefined,
+        maxDepth: typeof args.maxdepth === "number" ? args.maxdepth : undefined,
+        headless: args.headed !== true,
+        onEvent: (event) => {
+          if (event.kind !== "click") console.log(`[discover] ${event.text}`);
+        },
+      });
+      await fs.promises.mkdir(outDir, { recursive: true });
+      for (const flow of result.flows) {
+        await fs.promises.writeFile(path.join(outDir, path.basename(flow.file)), flow.content, "utf8");
+      }
+      await fs.promises.writeFile(
+        path.join(outDir, "discovery.json"),
+        `${JSON.stringify({ baseUrl: result.baseUrl, pages: result.pages.map(({ route, heading, title, path: via }) => ({ route, heading, title, via })), events: result.events }, null, 2)}\n`,
+        "utf8",
+      );
+      console.log(`[Bugmole] Discovered ${result.pages.length} pages and wrote ${result.flows.length} flows to ${path.relative(workspaceRoot, outDir) || "."}`);
+      if (result.pages.length === 0) process.exitCode = 1;
+    } finally {
+      // Holds the app's cookies and tokens: never outlives the exploration.
+      await fs.promises.rm(sessionDir, { recursive: true, force: true });
+    }
+    return;
+  }
+
   const cfg = loadConfig(configPath);
 
   if (mode === "reset") {

package/scripts/ensure-playwright.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Downloads the browsers Bugmole runs tests in, since the `playwright` package
+// installs only the library: without this, the first `bugmole run` or
+// `bugmole serve` on a new machine stops with "Chromium is not installed".
+// Runs as a postinstall step next to ensure-maestro.cjs, and like it never
+// fails the parent `npm install` — this is best-effort.
+//
+// It uses the package's own Playwright, so the browsers always match the
+// version Bugmole drives. Edge is left out: installing it needs admin rights
+// (sudo on Linux, a system package on macOS), so it stays a one-line opt-in.
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+// Chromium, Firefox and WebKit (Safari) are the browsers a run targets by
+// default; ffmpeg is what records a run's video.
+const BROWSERS = ["chromium", "firefox", "webkit", "ffmpeg"];
+
+function log(message) {
+  console.log(`[bugmole postinstall] ${message}`);
+}
+
+function skipReason(env = process.env) {
+  if (env.BUGMOLE_SKIP_PLAYWRIGHT_INSTALL === "true") return "BUGMOLE_SKIP_PLAYWRIGHT_INSTALL=true";
+  // A CI job that runs Bugmole's tests asks for the browsers explicitly.
+  if (env.BUGMOLE_PLAYWRIGHT_INSTALL === "true") return null;
+  // Playwright's own switch, which CI images and Docker builds already set.
+  if (env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD && env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD !== "0") return "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is set";
+  // CI installs dependencies on every job; several hundred MB of browsers
+  // each time is wasted unless the job runs tests, and then it says so.
+  if (env.CI && env.CI !== "false" && env.CI !== "0") return "running in CI";
+  return null;
+}
+
+// Playwright doesn't export its CLI, so find it the way npm does: through
+// the `bin` its package.json declares.
+function playwrightCli() {
+  try {
+    const manifest = require.resolve("playwright/package.json");
+    const bin = require(manifest).bin;
+    const entry = typeof bin === "string" ? bin : bin && bin.playwright;
+    return entry ? path.join(path.dirname(manifest), entry) : null;
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const reason = skipReason();
+  if (reason) {
+    log(`Skipping Playwright browser install (${reason}). Set BUGMOLE_PLAYWRIGHT_INSTALL=true to install them anyway, or later: npx playwright install ${BROWSERS.join(" ")}`);
+    return;
+  }
+  const cli = playwrightCli();
+  if (!cli) {
+    log("Playwright is not installed next to Bugmole, so there are no browsers to fetch yet.");
+    return;
+  }
+  log(`Installing Playwright browsers (${BROWSERS.join(", ")}). Already-installed ones are skipped.`);
+  const install = spawnSync(process.execPath, [cli, "install", ...BROWSERS], {
+    stdio: "inherit",
+    timeout: 10 * 60 * 1000,
+  });
+  if (install.error || install.status !== 0) {
+    log(
+      "Automatic browser install failed. Runs report the missing browser until it is installed: " +
+        `npx playwright install ${BROWSERS.join(" ")}`,
+    );
+    if (process.platform === "linux") {
+      log("On Linux the browsers also need system libraries: sudo npx playwright install-deps");
+    }
+    return;
+  }
+  log("Playwright browsers are ready. For Edge as well: npx playwright install msedge (needs admin rights).");
+  if (process.platform === "linux") {
+    log("If a browser fails to start on Linux, install its system libraries: sudo npx playwright install-deps");
+  }
+}
+
+module.exports = { BROWSERS, playwrightCli, skipReason };
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    log(`Skipping Playwright browser install after unexpected error: ${error.message}`);
+  }
+}

package/scripts/ensure-playwright.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const { BROWSERS, playwrightCli, skipReason } = require("./ensure-playwright.cjs") as {
+  BROWSERS: string[];
+  playwrightCli: () => string | null;
+  skipReason: (env: Record<string, string | undefined>) => string | null;
+};
+
+test("installing the CLI fetches the browsers a run targets by default, plus ffmpeg for video", () => {
+  assert.deepEqual(BROWSERS, ["chromium", "firefox", "webkit", "ffmpeg"]);
+  assert.ok(!BROWSERS.includes("msedge"), "Edge needs admin rights, so it stays opt-in");
+  const pkg = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")) as { scripts: Record<string, string> };
+  assert.match(pkg.scripts.postinstall, /ensure-playwright\.cjs/);
+});
+
+test("the browser download is skipped in CI and when either skip switch is set", () => {
+  assert.equal(skipReason({}), null);
+  assert.equal(skipReason({ CI: "false" }), null);
+  assert.match(skipReason({ CI: "true" }) ?? "", /CI/);
+  assert.match(skipReason({ BUGMOLE_SKIP_PLAYWRIGHT_INSTALL: "true" }) ?? "", /BUGMOLE_SKIP_PLAYWRIGHT_INSTALL/);
+  assert.match(skipReason({ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1" }) ?? "", /PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD/);
+  assert.equal(skipReason({ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "0" }), null);
+  assert.equal(skipReason({ CI: "true", BUGMOLE_PLAYWRIGHT_INSTALL: "true" }), null, "a CI job that runs tests can ask for the browsers");
+  assert.match(skipReason({ BUGMOLE_PLAYWRIGHT_INSTALL: "true", BUGMOLE_SKIP_PLAYWRIGHT_INSTALL: "true" }) ?? "", /SKIP/, "an explicit skip still wins");
+});
+
+test("finds Playwright's CLI even though the package doesn't export it", () => {
+  const cli = playwrightCli();
+  assert.ok(cli && cli.endsWith("cli.js"), `expected Playwright's cli.js, got ${cli}`);
+});

package/scripts/sync-launcher-version.cjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Pins the unscoped `bugmole` launcher (packages/bugmole) to the @bugmole/cli
+// version being released, so `npx bugmole` always installs that exact CLI.
+// The publish workflow runs this right before publishing the launcher.
+const fs = require("node:fs");
+const path = require("node:path");
+
+function syncLauncher(root = path.resolve(__dirname, "..")) {
+  const cli = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  const launcherPath = path.join(root, "packages", "bugmole", "package.json");
+  const launcher = JSON.parse(fs.readFileSync(launcherPath, "utf8"));
+  if (cli.name !== "@bugmole/cli") throw new Error(`Expected the root package to be @bugmole/cli, found ${cli.name}`);
+  launcher.version = cli.version;
+  launcher.dependencies = { ...launcher.dependencies, "@bugmole/cli": cli.version };
+  fs.writeFileSync(launcherPath, `${JSON.stringify(launcher, null, 2)}\n`);
+  return { version: launcher.version, dependency: launcher.dependencies["@bugmole/cli"] };
+}
+
+module.exports = { syncLauncher };
+
+if (require.main === module) {
+  const result = syncLauncher();
+  console.log(`bugmole launcher pinned to @bugmole/cli ${result.dependency}`);
+}

package/scripts/sync-launcher-version.test.ts

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const { syncLauncher } = require("./sync-launcher-version.cjs") as { syncLauncher: (root: string) => { version: string; dependency: string } };
+
+test("the bugmole launcher is released at the CLI's version and installs exactly that CLI", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "launcher-"));
+  mkdirSync(path.join(root, "packages", "bugmole"), { recursive: true });
+  writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "@bugmole/cli", version: "0.5.2" }));
+  writeFileSync(path.join(root, "packages", "bugmole", "package.json"), JSON.stringify({ name: "bugmole", version: "0.4.0", bin: { bugmole: "bin/bugmole.cjs" }, dependencies: { "@bugmole/cli": "^0.4.0" } }));
+  assert.deepEqual(syncLauncher(root), { version: "0.5.2", dependency: "0.5.2" });
+  const launcher = JSON.parse(readFileSync(path.join(root, "packages", "bugmole", "package.json"), "utf8"));
+  assert.equal(launcher.version, "0.5.2");
+  assert.equal(launcher.dependencies["@bugmole/cli"], "0.5.2");
+  assert.deepEqual(launcher.bin, { bugmole: "bin/bugmole.cjs" }, "everything else is left alone");
+});
+
+test("the real launcher's bin matches its package name, so npx bugmole knows what to run", () => {
+  const launcher = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "packages", "bugmole", "package.json"), "utf8"));
+  assert.equal(launcher.name, "bugmole");
+  assert.ok(launcher.bin.bugmole, "npx picks the bin named after the package when there are several");
+});

package/src/registry/migrations/0034_signup_attribution.sql

@@ -0,0 +1,19 @@
+-- Which affiliate code and campaign brought each new user. bugmole.com keeps
+-- the first visit's ref/utm_* tags in the bm_attr cookie; the dashboard sends
+-- them once after sign-in (POST /api/attribution). First touch wins: a row is
+-- written once and never overwritten. Scents reads this table.
+CREATE TABLE IF NOT EXISTS signup_attribution (
+  aegis_id      TEXT PRIMARY KEY REFERENCES aegis_users(id) ON DELETE CASCADE,
+  ref           TEXT,
+  utm_source    TEXT,
+  utm_medium    TEXT,
+  utm_campaign  TEXT,
+  utm_content   TEXT,
+  utm_term      TEXT,
+  landing_path  TEXT,
+  referrer_host TEXT,
+  first_seen_at TEXT,
+  created_at    TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_signup_attribution_ref ON signup_attribution(ref);
+CREATE INDEX IF NOT EXISTS idx_signup_attribution_campaign ON signup_attribution(utm_campaign);

package/src/registry/migrations/0035_domain_verify_file.sql

@@ -0,0 +1,6 @@
+-- How a domain was proven: 'dns' (a TXT record, which covers the domain and
+-- its subdomains) or 'file' (a file published on the site, which proves
+-- control of that one host only). Rows verified before this column existed
+-- were all DNS.
+ALTER TABLE workspace_domains ADD COLUMN verified_by TEXT;
+UPDATE workspace_domains SET verified_by = 'dns' WHERE status = 'verified';

package/src/registry-worker/core.ts

@@ -16,6 +16,8 @@ export interface Env extends EmailEnv {
   RUNNER_TOKEN_SECRET?: string;
   /** Service binding to the valkyrie-runner Worker that starts cloud-run containers. */
   RUNNER?: Fetcher;
+  /** Scents (bugmole-scents): checks that a typed referral code belongs to an affiliate. */
+  SCENTS?: Fetcher;
   /** Cloud runs executing at once across every workspace (default 20). */
   CLOUD_POOL_MAX?: string;
   /** Longest a cloud run may take before it is stopped, in minutes (default 60). */

package/src/registry-worker/domains/domains.test.ts

@@ -4,6 +4,7 @@ import type { Env } from "../core.js";
 import { call, createTestEnv, seedPlan, seedProject } from "../testing/harness.js";
 import {
   domainProvesToken,
+  fileProvesToken,
   hostMatchesVerifiedDomain,
   needsDomainVerification,
   normalizeDomain,
@@ -56,6 +57,31 @@ test("domainProvesToken only accepts the exact token at the exact record name",
   assert.deepEqual(calls, ["_bugmole-verify.example.com", "_bugmole-verify.other.com"]);
 });
 
+test("a published file only proves the exact token, served directly, on the exact host", async () => {
+  const token = "bugmole-domain-verify=abc123";
+  const asked: string[] = [];
+  const site = (async (input: RequestInfo | URL) => {
+    const url = String(input);
+    asked.push(url);
+    if (url === "https://app.example.com/.well-known/bugmole-verification.txt") return new Response(`# Bugmole\n${token}\n`);
+    if (url === "https://moved.example.com/.well-known/bugmole-verification.txt") return new Response(null, { status: 302, headers: { location: "https://app.example.com/.well-known/bugmole-verification.txt" } });
+    if (url === "https://inline.example.com/.well-known/bugmole-verification.txt") return new Response(`not-${token}`);
+    return new Response("Not found", { status: 404 });
+  }) as unknown as typeof fetch;
+  assert.equal(await fileProvesToken("app.example.com", token, site), true);
+  assert.equal(await fileProvesToken("moved.example.com", token, site), false, "a redirect could hand the proof to another host");
+  assert.equal(await fileProvesToken("inline.example.com", token, site), false, "the token must be a line of its own");
+  assert.equal(await fileProvesToken("other.example.com", token, site), false);
+  assert.equal(await fileProvesToken("app.example.com", token, (async () => { throw new Error("offline"); }) as unknown as typeof fetch), false);
+  assert.ok(asked.every((url) => url.startsWith("https://")), "only ever over HTTPS");
+});
+
+test("a file-verified host covers only itself; a DNS-verified domain covers its subdomains", () => {
+  assert.equal(hostMatchesVerifiedDomain("app.example.com", "app.example.com", "file"), true);
+  assert.equal(hostMatchesVerifiedDomain("admin.app.example.com", "app.example.com", "file"), false);
+  assert.equal(hostMatchesVerifiedDomain("admin.app.example.com", "app.example.com", "dns"), true);
+});
+
 // --- Routes and enforcement --------------------------------------------------------------------
 
 /** A fake DoH resolver that answers real (name -> token) pairs, like a real zone would. */
@@ -108,7 +134,8 @@ test("verification checks the real TXT record and rejects a stranger's guess", a
 
   const tooSoon = await call(env, "POST", `/api/workspaces/${workspaceId}/domains/${id}/verify`, { as: owner });
   assert.equal(tooSoon.status, 400);
-  assert.equal(tooSoon.json.error, "dns_verification_failed");
+  assert.equal(tooSoon.json.error, "verification_failed");
+  assert.match(tooSoon.json.message, /\.well-known\/bugmole-verification\.txt/);
 
   const wrongValue = await call(env, "POST", `/api/workspaces/${workspaceId}/domains/${id}/verify`, { as: "user_stranger" });
   assert.equal(wrongValue.status, 403, "verifying is also owner/admin-only");
@@ -208,3 +235,39 @@ test("adding a domain is limited so a workspace can't grow this table without bo
   const overLimit = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "one-too-many.example.com" } });
   assert.equal(overLimit.status, 422);
 });
+
+test("someone without DNS access verifies one subdomain by publishing a file, and only that host opens up", async () => {
+  const files = new Map<string, string>();
+  const site = (async (input: RequestInfo | URL) => {
+    const url = new URL(String(input));
+    if (url.hostname === "cloudflare-dns.com") return Response.json({ Answer: [] });
+    const body = files.get(`${url.hostname}${url.pathname}`);
+    return body === undefined ? new Response("Not found", { status: 404 }) : new Response(body);
+  }) as unknown as typeof fetch;
+  const { env, workspaceId, owner, projectId } = await workspace({ DOMAIN_VERIFY_FETCH: site } as Partial<Env>);
+  await call(env, "POST", `/api/projects/${projectId}/environments`, { as: owner, body: { id: "prod", name: "Prod", baseUrl: "https://shop.example.com/" } });
+  await call(env, "POST", `/api/projects/${projectId}/environments`, { as: owner, body: { id: "admin", name: "Admin", baseUrl: "https://admin.shop.example.com/" } });
+
+  const added = await call(env, "POST", `/api/workspaces/${workspaceId}/domains`, { as: owner, body: { domain: "shop.example.com" } });
+  assert.deepEqual(added.json.domain.file, {
+    url: "https://shop.example.com/.well-known/bugmole-verification.txt",
+    content: added.json.domain.txtRecord.value,
+  });
+  files.set("shop.example.com/.well-known/bugmole-verification.txt", `${added.json.domain.file.content}\n`);
+  const verified = await call(env, "POST", `/api/workspaces/${workspaceId}/domains/${added.json.domain.id}/verify`, { as: owner });
+  assert.equal(verified.status, 200);
+  assert.equal(verified.json.method, "file");
+  assert.equal((await call(env, "GET", `/api/workspaces/${workspaceId}/domains`, { as: owner })).json.domains[0].verifiedBy, "file");
+
+  const allowed = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "f1", executionMode: "cloud", environmentId: "prod" },
+  });
+  assert.equal(allowed.status, 201, JSON.stringify(allowed.json));
+  const deeper = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "f2", executionMode: "cloud", environmentId: "admin" },
+  });
+  assert.equal(deeper.status, 403, "a file on one host says nothing about the hosts under it");
+  assert.equal(deeper.json.code, "domain_not_verified");
+});

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

@@ -1,16 +1,20 @@
 // Workspace domain verification: prove control of a domain by DNS TXT record
+// (covers subdomains) or by publishing a file on the site (that host only)
 // before Bugmole Cloud will explore or run against a host on it. See
 // ../domains.ts for why, and the normalization/matching/DNS-lookup helpers.
 import {
   domainProvesToken,
   dohTxtLookupWith,
+  DOMAIN_VERIFY_FILE,
   DOMAIN_VERIFY_PREFIX,
+  fileProvesToken,
   hostMatchesVerifiedDomain,
   needsDomainVerification,
   newVerificationToken,
   normalizeDomain,
   targetHost,
   type TxtLookup,
+  type VerificationMethod,
 } from "../domains.js";
 import type { AuthedRouteContext } from "../routes/index.js";
 import { matchPath, registerRoutes } from "../routes/index.js";
@@ -20,27 +24,37 @@ import { actorOf, recordAudit } from "../org/audit.js";
 
 const MAX_DOMAINS_PER_WORKSPACE = 25;
 
+function fetchFor(env: Env): typeof fetch {
+  return (env as Env & { DOMAIN_VERIFY_FETCH?: typeof fetch }).DOMAIN_VERIFY_FETCH ?? fetch;
+}
+
 function lookupFor(env: Env): TxtLookup {
-  return dohTxtLookupWith((env as Env & { DOMAIN_VERIFY_FETCH?: typeof fetch }).DOMAIN_VERIFY_FETCH ?? fetch);
+  return dohTxtLookupWith(fetchFor(env));
 }
 
 type DomainRow = {
   id: string;
   domain: string;
   status: "pending" | "verified";
+  verifiedBy?: VerificationMethod | null;
   createdAt: string;
   verifiedAt: string | null;
   lastCheckError: string | null;
 };
 
 function withRecord(row: DomainRow, token: string) {
-  return { ...row, txtRecord: { name: `${DOMAIN_VERIFY_PREFIX}.${row.domain}`, value: token } };
+  return {
+    ...row,
+    txtRecord: { name: `${DOMAIN_VERIFY_PREFIX}.${row.domain}`, value: token },
+    // For a site whose DNS the person can't change, such as one subdomain.
+    file: { url: `https://${row.domain}${DOMAIN_VERIFY_FILE}`, content: token },
+  };
 }
 
 async function listDomains({ env, principal }: AuthedRouteContext, workspaceId: string): Promise<Response> {
   if (!(await memberOfWorkspace(env, principal, workspaceId))) return response({ error: "Workspace scope is not allowed" }, 403);
   const rows = await env.DB.prepare(`
-    SELECT id, domain, verification_token AS verificationToken, status, created_at AS createdAt, verified_at AS verifiedAt, last_check_error AS lastCheckError
+    SELECT id, domain, verification_token AS verificationToken, status, verified_by AS verifiedBy, created_at AS createdAt, verified_at AS verifiedAt, last_check_error AS lastCheckError
     FROM workspace_domains WHERE workspace_id = ? ORDER BY created_at ASC
   `).bind(workspaceId).all<DomainRow & { verificationToken: string }>();
   return response({
@@ -62,7 +76,7 @@ async function addDomain({ env, principal, request }: AuthedRouteContext, worksp
   }
   const count = await env.DB.prepare("SELECT COUNT(*) AS count FROM workspace_domains WHERE workspace_id = ?").bind(workspaceId).first<{ count: number }>();
   if ((count?.count ?? 0) >= MAX_DOMAINS_PER_WORKSPACE) return response({ error: `A workspace can add at most ${MAX_DOMAINS_PER_WORKSPACE} domains.` }, 422);
-  const existing = await env.DB.prepare("SELECT id, verification_token AS verificationToken, status, created_at AS createdAt, verified_at AS verifiedAt, last_check_error AS lastCheckError FROM workspace_domains WHERE workspace_id = ? AND domain = ?")
+  const existing = await env.DB.prepare("SELECT id, verification_token AS verificationToken, status, verified_by AS verifiedBy, created_at AS createdAt, verified_at AS verifiedAt, last_check_error AS lastCheckError FROM workspace_domains WHERE workspace_id = ? AND domain = ?")
     .bind(workspaceId, domain).first<DomainRow & { verificationToken: string }>();
   if (existing) return response({ domain: withRecord({ ...existing, domain }, existing.verificationToken) }, 200);
   const id = newId("dom");
@@ -83,16 +97,19 @@ async function verifyDomain({ env, principal, request }: AuthedRouteContext, wor
     .bind(id, workspaceId).first<{ domain: string; verificationToken: string; status: string }>();
   if (!row) return response({ error: "Not found" }, 404);
   if (row.status === "verified") return response({ verified: true });
-  const proved = await domainProvesToken(row.domain, row.verificationToken, lookupFor(env));
-  if (!proved) {
-    const message = "We couldn't find that TXT record yet. DNS changes can take a while to propagate — try again shortly.";
+  // Either proof will do; DNS first, since it covers more.
+  const method: VerificationMethod | null = await domainProvesToken(row.domain, row.verificationToken, lookupFor(env))
+    ? "dns"
+    : await fileProvesToken(row.domain, row.verificationToken, fetchFor(env)) ? "file" : null;
+  if (!method) {
+    const message = `We couldn't find the TXT record or the file at https://${row.domain}${DOMAIN_VERIFY_FILE} yet. DNS changes can take a while to propagate — try again shortly.`;
     await env.DB.prepare("UPDATE workspace_domains SET last_check_error = ? WHERE id = ?").bind(message, id).run();
-    return response({ error: "dns_verification_failed", message }, 400);
+    return response({ error: "verification_failed", message }, 400);
   }
-  await env.DB.prepare("UPDATE workspace_domains SET status = 'verified', verified_at = ?, last_check_error = NULL WHERE id = ?")
-    .bind(new Date().toISOString(), id).run();
-  await recordAudit(env, actorOf(principal), { workspaceId, action: "domain.verified", targetType: "domain", targetId: id, data: { domain: row.domain } }, request);
-  return response({ verified: true });
+  await env.DB.prepare("UPDATE workspace_domains SET status = 'verified', verified_by = ?, verified_at = ?, last_check_error = NULL WHERE id = ?")
+    .bind(method, new Date().toISOString(), id).run();
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "domain.verified", targetType: "domain", targetId: id, data: { domain: row.domain, method } }, request);
+  return response({ verified: true, method });
 }
 
 async function removeDomain({ env, principal, request }: AuthedRouteContext, workspaceId: string, id: string): Promise<Response> {
@@ -115,9 +132,9 @@ async function removeDomain({ env, principal, request }: AuthedRouteContext, wor
 export async function requireVerifiedDomainForCloud(env: Env, workspaceId: string, url: string): Promise<Response | null> {
   const host = targetHost(url);
   if (!host || !needsDomainVerification(host)) return null;
-  const rows = await env.DB.prepare("SELECT domain FROM workspace_domains WHERE workspace_id = ? AND status = 'verified'")
-    .bind(workspaceId).all<{ domain: string }>();
-  if (rows.results.some((row) => hostMatchesVerifiedDomain(host, row.domain))) return null;
+  const rows = await env.DB.prepare("SELECT domain, verified_by AS verifiedBy FROM workspace_domains WHERE workspace_id = ? AND status = 'verified'")
+    .bind(workspaceId).all<{ domain: string; verifiedBy: VerificationMethod | null }>();
+  if (rows.results.some((row) => hostMatchesVerifiedDomain(host, row.domain, row.verifiedBy ?? "dns"))) return null;
   return response({
     error: `Verify that this workspace owns ${host} before running it on Bugmole Cloud.`,
     code: "domain_not_verified",

package/src/registry-worker/domains.ts

@@ -1,5 +1,5 @@
 // Domain ownership: a workspace must prove it controls a domain, by DNS TXT
-// record, before Bugmole Cloud will explore or run against a host on it.
+// record or by publishing a file on the site, before Bugmole Cloud will explore or run against a host on it.
 // Without this, a workspace's cloud minutes could point Bugmole's own IPs
 // at any third-party site — using Bugmole as an anonymous crawler against a
 // domain nobody in the workspace actually owns. Self-hosted runs and
@@ -8,6 +8,10 @@
 import { randomToken } from "./core.js";
 
 export const DOMAIN_VERIFY_PREFIX = "_bugmole-verify";
+/** Where the file proof lives. Under /.well-known/ so an ordinary upload folder can't satisfy it. */
+export const DOMAIN_VERIFY_FILE = "/.well-known/bugmole-verification.txt";
+
+export type VerificationMethod = "dns" | "file";
 
 export function newVerificationToken(): string {
   return `bugmole-domain-verify=${randomToken(20)}`;
@@ -61,9 +65,15 @@ export function needsDomainVerification(host: string): boolean {
   return !isPrivateHost(host);
 }
 
-export function hostMatchesVerifiedDomain(host: string, domain: string): boolean {
+/**
+ * DNS proves the whole zone, so it covers subdomains. A published file only
+ * proves whoever runs that one host — on shared hosting, the next subdomain
+ * over may belong to someone else — so it covers exactly that host.
+ */
+export function hostMatchesVerifiedDomain(host: string, domain: string, method: VerificationMethod = "dns"): boolean {
   const h = host.toLowerCase();
   const d = domain.toLowerCase();
+  if (method === "file") return h === d;
   return h === d || h.endsWith(`.${d}`);
 }
 
@@ -86,3 +96,31 @@ export async function domainProvesToken(domain: string, token: string, lookup: T
   const records = await lookup(`${DOMAIN_VERIFY_PREFIX}.${domain}`).catch(() => [] as string[]);
   return records.includes(token);
 }
+
+/**
+ * The file proof: https://<domain>/.well-known/bugmole-verification.txt
+ * answers 200 itself (no redirect, which could hand the proof to another
+ * host) with the token on a line of its own. Bounded in time and size.
+ */
+export async function fileProvesToken(domain: string, token: string, doFetch: typeof fetch = fetch): Promise<boolean> {
+  try {
+    const res = await doFetch(`https://${domain}${DOMAIN_VERIFY_FILE}`, {
+      redirect: "manual",
+      headers: { accept: "text/plain", "user-agent": "Bugmole domain verification" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (res.status !== 200 || !res.body) return false;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let text = "";
+    while (text.length < 4096) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      text += decoder.decode(value, { stream: true });
+    }
+    await reader.cancel().catch(() => undefined);
+    return text.slice(0, 4096).split(/\r?\n/).some((line) => line.trim() === token);
+  } catch {
+    return false;
+  }
+}