@bugmole/cli 0.5.0 → 0.6.0

package/src/runtime/secret-sources.ts

@@ -0,0 +1,176 @@
+// Where a flow's secrets come from. A flow types `{{secret.NAME}}`, which
+// reads BUGMOLE_FLOW_SECRET_NAME. Setting that variable by hand is the oldest
+// way; this file lets a project keep each value somewhere safe and name it by
+// reference instead, so no password lives in the repository, the config, a
+// chat with an agent, or Bugmole:
+//
+//   secrets:
+//     ADMIN_TOKEN: gcpsm://projects/acme/secrets/qa-admin   # Google Secret Manager
+//     API_KEY: awssm://us-east-1/qa/api#key                 # AWS Secrets Manager (#key reads a JSON field)
+//     PIN: keychain://some-service/PIN                       # an existing OS keychain entry
+//     OTHER: env://MY_CI_VARIABLE                           # an environment variable
+//
+// A name with no reference is read from this machine's secure store, which
+// `bugmole secrets set NAME` writes: an encrypted vault whose one key is in
+// the OS credential store (local-vault.ts), or the OS keychain itself where
+// that vault isn't installed. Cloud vaults are read by the vendored resolver
+// in ../vendor/byok.ts.
+
+import {
+  deleteKeychain as deleteEntry,
+  formatReference,
+  keychainHas,
+  parseReference,
+  readiness,
+  resolveReference,
+  SOURCE_NAME,
+  writeKeychain as writeEntry,
+  type ByokDeps,
+  type SecretReference as VaultReference,
+} from "../vendor/byok.js";
+import { openLocalVault, type LocalVaultLike } from "./local-vault.js";
+
+/** A value in this machine's secure store, for one project. */
+export type LocalReference = { kind: "local"; project: string; name: string };
+export type SecretReference = VaultReference | LocalReference;
+
+export type SecretDeps = ByokDeps & {
+  /** This machine's vault: undefined opens the real one, null means none is installed. */
+  localVault?: LocalVaultLike | null;
+};
+
+export const SOURCE_LABEL: Record<SecretReference["kind"], string> = {
+  ...SOURCE_NAME,
+  local: "this machine's secure store",
+};
+export const SECRET_NAME = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+
+/** Parses a reference; `local://NAME` needs the project it belongs to. */
+export function parseSecretReference(value: unknown, projectId = "default"): SecretReference | null {
+  if (typeof value === "string") {
+    const local = /^local:\/\/([A-Za-z][A-Za-z0-9_]{0,63})$/.exec(value.trim());
+    if (local) return { kind: "local", project: projectId, name: local[1] };
+  }
+  return parseReference(value);
+}
+
+export function describeReference(reference: SecretReference): string {
+  return reference.kind === "local" ? `local://${reference.name}` : formatReference(reference);
+}
+
+/** Where `bugmole secrets set NAME` keeps a project's value. */
+export function defaultLocalReference(projectId: string, name: string): LocalReference {
+  return { kind: "local", project: projectId, name };
+}
+
+/** The vault entry name, and the keychain entry used where there is no vault. */
+const entryName = (reference: LocalReference) => `${reference.project}/${reference.name}`;
+const keychainFallback = (reference: LocalReference) => ({ kind: "keychain" as const, service: `bugmole:${reference.project}`, account: reference.name });
+
+async function localVault(deps: SecretDeps): Promise<LocalVaultLike | null> {
+  return deps.localVault !== undefined ? deps.localVault : openLocalVault(deps.env);
+}
+
+export async function resolveSecret(reference: SecretReference, deps: SecretDeps = {}): Promise<string> {
+  if (reference.kind !== "local") return resolveReference(reference, deps);
+  const vault = await localVault(deps);
+  if (vault) {
+    const value = vault.get(entryName(reference));
+    if (value === null || value === "") throw new Error(`${reference.name} isn't in this machine's secure store`);
+    return value;
+  }
+  try {
+    return await resolveReference(keychainFallback(reference), deps);
+  } catch {
+    throw new Error(`${reference.name} isn't in this machine's secure store`);
+  }
+}
+
+/** Keeps a value in this machine's secure store; says where it went. */
+export async function writeLocal(reference: LocalReference, value: string, deps: SecretDeps = {}): Promise<"vault" | "keychain"> {
+  const vault = await localVault(deps);
+  if (vault) {
+    vault.set(entryName(reference), value);
+    return "vault";
+  }
+  await writeEntry(keychainFallback(reference), value, `Bugmole ${reference.name}`, deps);
+  return "keychain";
+}
+
+export async function deleteLocal(reference: LocalReference, deps: SecretDeps = {}): Promise<boolean> {
+  const vault = await localVault(deps);
+  if (vault) return vault.delete(entryName(reference));
+  return deleteEntry(keychainFallback(reference), deps);
+}
+
+async function localHas(reference: LocalReference, deps: SecretDeps): Promise<boolean> {
+  const vault = await localVault(deps);
+  return vault ? vault.has(entryName(reference)) : keychainHas(keychainFallback(reference), deps);
+}
+
+/**
+ * The project's `secrets:` map from its config, keeping well-formed entries.
+ * Anything else is reported, never echoed: it may be a pasted password.
+ */
+export function secretMap(cfg: { secrets?: unknown; project?: { id?: string } } | null | undefined): { map: Record<string, SecretReference>; problems: string[] } {
+  const map: Record<string, SecretReference> = {};
+  const problems: string[] = [];
+  const raw = cfg?.secrets;
+  if (raw === undefined || raw === null) return { map, problems };
+  if (typeof raw !== "object" || Array.isArray(raw)) return { map, problems: ["secrets must map each name to a reference"] };
+  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!SECRET_NAME.test(name)) {
+      problems.push(`secrets.${name}: a name is letters, digits and _`);
+      continue;
+    }
+    const reference = parseSecretReference(value, cfg?.project?.id ?? "default");
+    if (!reference) {
+      problems.push(`secrets.${name}: not a reference (gcpsm://, awssm://, keychain://, env:// or local://). Don't put the value itself in the config.`);
+      continue;
+    }
+    map[name] = reference;
+  }
+  return { map, problems };
+}
+
+export type SecretStatus = {
+  name: string;
+  source: SecretReference["kind"] | "unset";
+  reference?: string;
+  /** Whether this machine can probably supply it, checked without reading the value. */
+  ready: boolean;
+  detail: string;
+};
+
+/** What this machine can supply for each name, without reading any value. */
+export async function secretStatuses(
+  names: readonly string[],
+  map: Record<string, SecretReference>,
+  projectId: string,
+  deps: SecretDeps = {},
+): Promise<SecretStatus[]> {
+  const env = deps.env ?? process.env;
+  const statuses: SecretStatus[] = [];
+  for (const name of [...new Set(names)].sort()) {
+    if (env[`BUGMOLE_FLOW_SECRET_${name}`]) {
+      statuses.push({ name, source: "env", reference: `env://BUGMOLE_FLOW_SECRET_${name}`, ready: true, detail: "Set in this machine's environment" });
+      continue;
+    }
+    const mapped = map[name];
+    const reference = mapped ?? defaultLocalReference(projectId, name);
+    if (reference.kind === "local") {
+      const ready = await localHas(reference, deps);
+      statuses.push({
+        name,
+        source: ready || mapped ? "local" : "unset",
+        reference: describeReference(reference),
+        ready,
+        detail: ready ? "In this machine's secure store" : `Not set: run bugmole secrets set ${name}${mapped ? "" : ", or map it to your vault under secrets: in the config"}`,
+      });
+      continue;
+    }
+    const { ready, detail } = await readiness(reference, deps);
+    statuses.push({ name, source: reference.kind, reference: describeReference(reference), ready, detail });
+  }
+  return statuses;
+}

package/src/runtime/secrets-cli.ts

@@ -0,0 +1,146 @@
+// `bugmole secrets`: what the project's flows need, where each value comes
+// from, and a place on this machine to keep the ones that have no vault.
+//
+//   bugmole secrets                 list every secret the flows use, and whether this machine can supply it
+//   bugmole secrets set NAME        store a value in this machine's secure store (typed, never echoed; or piped on stdin)
+//   bugmole secrets delete NAME     remove it
+//
+// Values never print. An agent asked for a password should point the person
+// at `bugmole secrets set`, which they run in their own terminal.
+
+import fs from "node:fs";
+import path from "node:path";
+import { referencedSecretNames } from "./flow-language.js";
+import {
+  defaultLocalReference,
+  deleteLocal,
+  describeReference,
+  SECRET_NAME,
+  secretMap,
+  secretStatuses,
+  SOURCE_LABEL,
+  writeLocal,
+  type SecretDeps,
+  type SecretStatus,
+} from "./secret-sources.js";
+
+type Config = { project?: { id?: string }; runtime?: { spec_dir?: string }; secrets?: unknown };
+
+/** Every `{{secret.NAME}}` in the project's flow files. */
+export function flowSecretNames(directories: readonly string[]): string[] {
+  const names = new Set<string>();
+  const visit = (directory: string, depth: number) => {
+    if (depth > 6 || !fs.existsSync(directory)) return;
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") && entry.name !== ".maestro") continue;
+      if (entry.name === "node_modules") continue;
+      const full = path.join(directory, entry.name);
+      if (entry.isDirectory()) visit(full, depth + 1);
+      else if (/\.ya?ml$/i.test(entry.name)) {
+        for (const name of referencedSecretNames(fs.readFileSync(full, "utf8"))) names.add(name);
+      }
+    }
+  };
+  for (const directory of directories) visit(directory, 0);
+  return [...names].sort();
+}
+
+/** The secrets a project uses (its flows plus its config's map) and what this machine can supply. */
+export async function projectSecretStatuses(cfg: Config, workspaceRoot: string, deps: SecretDeps = {}): Promise<{ statuses: SecretStatus[]; problems: string[] }> {
+  const { map, problems } = secretMap(cfg);
+  const specDir = path.resolve(workspaceRoot, cfg.runtime?.spec_dir || "./spec");
+  // Flows live in spec/ by default, but the docs and many projects keep them
+  // in flows/ or .maestro/ at the root.
+  const flowDirs = [specDir, path.resolve(workspaceRoot, "flows"), path.resolve(workspaceRoot, ".maestro")];
+  const names = [...flowSecretNames([...new Set(flowDirs)]), ...Object.keys(map)];
+  const statuses = await secretStatuses(names, map, cfg.project?.id ?? "default", deps);
+  return { statuses, problems };
+}
+
+async function readValue(name: string, stdin: NodeJS.ReadStream, stderr: NodeJS.WriteStream): Promise<string> {
+  if (!stdin.isTTY) {
+    // Piped: from a password manager's CLI, say. One trailing newline is the pipe's, not the value's.
+    const chunks: Buffer[] = [];
+    for await (const chunk of stdin) chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+  }
+  stderr.write(`Value for ${name} (not shown): `);
+  stdin.setRawMode?.(true);
+  stdin.resume();
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const done = (error?: Error) => {
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      stderr.write("\n");
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const onData = (chunk: Buffer) => {
+      for (const char of String(chunk)) {
+        if (char === "\r" || char === "\n") return done();
+        if (char === "\u0003") return done(new Error("Cancelled"));
+        if (char === "\u007f" || char === "\b") value = value.slice(0, -1);
+        else value += char;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+export async function runSecretsCommand(
+  cfg: Config,
+  argv: readonly string[],
+  io: { workspaceRoot: string; stdin?: NodeJS.ReadStream; stdout?: NodeJS.WriteStream; stderr?: NodeJS.WriteStream; deps?: SecretDeps } = { workspaceRoot: process.cwd() },
+): Promise<number> {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const projectId = cfg.project?.id ?? "default";
+  const rest = argv.slice(argv.indexOf("secrets") + 1).filter((arg) => !arg.startsWith("--"));
+  const [action = "list", name] = rest;
+
+  if (action === "list") {
+    const { statuses, problems } = await projectSecretStatuses(cfg, io.workspaceRoot, io.deps);
+    for (const problem of problems) stderr.write(`[Bugmole] ${problem}\n`);
+    if (!statuses.length) {
+      stdout.write("No flow uses {{secret.NAME}} and the config maps no secrets.\n");
+      return 0;
+    }
+    for (const status of statuses) {
+      const source = status.source === "unset" ? "not set" : SOURCE_LABEL[status.source];
+      stdout.write(`${status.ready ? "✓" : "✗"} ${status.name}  ${source}${status.reference ? `  ${status.reference}` : ""}\n    ${status.detail}\n`);
+    }
+    return statuses.every((status) => status.ready) ? 0 : 1;
+  }
+
+  if (action !== "set" && action !== "delete") {
+    stderr.write("Usage: bugmole secrets [list] | set NAME | delete NAME\n");
+    return 2;
+  }
+  if (!name || !SECRET_NAME.test(name)) {
+    stderr.write(`Usage: bugmole secrets ${action} NAME (letters, digits and _)\n`);
+    return 2;
+  }
+  const { map } = secretMap(cfg);
+  const mapped = map[name];
+  if (mapped && mapped.kind !== "local") {
+    stderr.write(`${name} comes from ${SOURCE_LABEL[mapped.kind]} (${describeReference(mapped)}); change it there.\n`);
+    return 1;
+  }
+  const reference = mapped ?? defaultLocalReference(projectId, name);
+  if (reference.kind !== "local") return 1;
+  if (action === "delete") {
+    const removed = await deleteLocal(reference, io.deps);
+    stdout.write(removed ? `Removed ${name} from this machine's secure store.\n` : `${name} wasn't in this machine's secure store.\n`);
+    return removed ? 0 : 1;
+  }
+  const value = await readValue(name, io.stdin ?? process.stdin, stderr);
+  if (!value) {
+    stderr.write("Nothing stored: the value was empty.\n");
+    return 1;
+  }
+  await writeLocal(reference, value, io.deps);
+  stdout.write(`Stored ${name} in this machine's secure store. Flows that type {{secret.${name}}} use it on this machine.\n`);
+  return 0;
+}

package/src/runtime/serve-worker.ts

@@ -1,14 +1,17 @@
 import os from "node:os";
 import type WebSocket from "ws";
-import { ControlPlaneClient, RegistryRequestError, type RegistryRun } from "../registry/control-plane-client.js";
+import { ControlPlaneClient, RegistryRequestError, isProjectInactive, projectInactiveMessage, type RegistryRun } from "../registry/control-plane-client.js";
+import { detectProjectIdentity } from "./project-identity.js";
 import { executeRegistryRun, registryDeviceAccess } from "./run-job.js";
 import { connectServeGateway } from "./serve-gateway.js";
 import { runNextAgentTask } from "./cursor-driver-run.js";
 import { reconcilePipeline } from "./pipeline.js";
 import { publishProjectSpec } from "./project-spec.js";
 import { recordRunVerdicts } from "./record-run-verdicts.js";
-import { isClaimableTask, MAX_TASK_ATTEMPTS } from "../registry/task-scheduling.js";
+import { isClaimableTask, MAX_TASK_ATTEMPTS, workerApprovalMode } from "../registry/task-scheduling.js";
+import { applyAcceptedProposals } from "./apply-proposals.js";
 import { DISCOVERY_TASK_TYPE, runDiscoveryTask } from "./discovery-task.js";
+import { discoveryLimitsFromEnv } from "./site-discovery.js";
 
 export { RUN_HEARTBEAT_MS } from "./run-job.js";
 
@@ -29,9 +32,30 @@ export function workerTasksEnabled(env: Record<string, string | undefined> = pro
   return env.BUGMOLE_WORKER_TASKS?.trim().toLowerCase() !== "false";
 }
 
-/** Another worker claimed the run first. That is not a failure of the run. */
+/** Another worker claimed the run first. That is not a failure of the run (a paused project is its own case). */
 export function isClaimConflict(error: unknown): boolean {
-  return error instanceof RegistryRequestError && error.status === 409;
+  return error instanceof RegistryRequestError && error.status === 409 && !isProjectInactive(error);
+}
+
+/**
+ * Reports which app this project is (so teammates' clones join it, and
+ * monorepo apps stay separate) and says so when the project is paused.
+ * Best-effort: serving never waits on it or fails because of it.
+ */
+export async function announceProjectIdentity(
+  client: Pick<ControlPlaneClient, "reportIdentity">,
+  projectId: string,
+  options: { cwd: string; appPath?: string },
+  log: Pick<Console, "log" | "warn"> = console,
+): Promise<void> {
+  const detection = detectProjectIdentity({ cwd: options.cwd, appPath: options.appPath });
+  if (!detection.identity) return;
+  try {
+    const reply = await client.reportIdentity(detection.identity as Record<string, unknown>);
+    if (reply.inactiveAt) log.warn(`[Bugmole] ${projectInactiveMessage(projectId, reply.activateUrl)}`);
+  } catch (error) {
+    if (error instanceof RegistryRequestError && error.detail) log.warn(`[Bugmole] ${error.detail}`);
+  }
 }
 
 export async function startServeWorker(cfg: any): Promise<void> {
@@ -54,6 +78,11 @@ export async function startServeWorker(cfg: any): Promise<void> {
   // Consecutive failed runs per flow, so a run that keeps crashing stops
   // being retried forever. See the catch in processRun.
   const runFailures = new Map<string, number>();
+  let pausedNoticeShown = false;
+  void announceProjectIdentity(client, projectId, {
+    cwd: process.cwd(),
+    appPath: cfg.project?.app_path ?? cfg.project?.appPath,
+  }).catch(() => undefined);
 
   const processRun = async (run: RegistryRun) => {
     if (active.has(run.id)) return;
@@ -63,6 +92,14 @@ export async function startServeWorker(cfg: any): Promise<void> {
         await client.claimRun(run.id, workerId);
       } catch (error) {
         if (isClaimConflict(error)) return;
+        if (isProjectInactive(error)) {
+          // Not the run's fault: it waits, queued, until someone activates the project.
+          if (!pausedNoticeShown) {
+            pausedNoticeShown = true;
+            console.warn(`[Bugmole] ${projectInactiveMessage(projectId, typeof error.body?.activateUrl === "string" ? error.body.activateUrl : null)}`);
+          }
+          return;
+        }
         throw error;
       }
       const result = await executeRegistryRun(cfg, client, run, {
@@ -89,6 +126,8 @@ export async function startServeWorker(cfg: any): Promise<void> {
               reason: (item as { reason?: { code?: string; message?: string } }).reason,
             })),
             run.id,
+            undefined,
+            run.caseScope,
           );
           if (judged) {
             console.log("[Bugmole] Recorded " + judged.judged + " case verdicts for " + judged.caseSetId);
@@ -129,6 +168,7 @@ export async function startServeWorker(cfg: any): Promise<void> {
             [],
             run.id,
             `The run failed ${failures} times and never reached this step. Last error: ${message}`,
+            run.caseScope,
           ).catch(() => undefined);
           console.warn(
             "[Bugmole] " + run.journeyId + " failed " + failures
@@ -193,10 +233,10 @@ export async function startServeWorker(cfg: any): Promise<void> {
     discoveryInFlight = true;
     try {
       const { tasks } = await client.listTasks();
-      const next = tasks.find((task) => task.taskType === DISCOVERY_TASK_TYPE && task.executionMode !== "cloud" && isClaimableTask(task));
+      const next = tasks.find((task) => task.taskType === DISCOVERY_TASK_TYPE && task.executionMode !== "cloud" && isClaimableTask(task, Date.now(), workerApprovalMode()));
       if (next) {
         console.log(`[Bugmole] Exploring for discovery task ${next.id}`);
-        await runDiscoveryTask(cfg, client, next, workerId);
+        await runDiscoveryTask(cfg, client, next, workerId, undefined, { limits: discoveryLimitsFromEnv() });
       }
     } catch (error) {
       console.warn(`[Bugmole] Discovery poll failed: ${error instanceof Error ? error.message : error}`);
@@ -205,6 +245,23 @@ export async function startServeWorker(cfg: any): Promise<void> {
     }
   };
 
+  // Accepted spec proposals for a project on its own storage wait for a
+  // worker to write them; Bugmole storage applies them in the registry.
+  let proposalsInFlight = false;
+  const pollProposals = async () => {
+    if (proposalsInFlight || cfg.storage?.provider === "bugmole") return;
+    proposalsInFlight = true;
+    try {
+      for (const result of await applyAcceptedProposals(cfg, client)) {
+        console.log(`[Bugmole] Proposal ${result.id} ${result.outcome}: ${result.detail}`);
+      }
+    } catch (error) {
+      console.warn(`[Bugmole] Applying proposals failed: ${error instanceof Error ? error.message : error}`);
+    } finally {
+      proposalsInFlight = false;
+    }
+  };
+
   const poll = async () => {
     try {
       const { runs } = await client.listRuns();
@@ -216,6 +273,7 @@ export async function startServeWorker(cfg: any): Promise<void> {
       console.warn(`[Bugmole] Worker registry poll failed: ${error instanceof Error ? error.message : error}`);
     }
     void pollDiscovery();
+    void pollProposals();
     if (tasksEnabled) void pollTasks();
   };
 

package/src/runtime/site-discovery.test.ts

@@ -5,16 +5,16 @@ import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { chromium } from "playwright";
-import { discoverableRoute, discoverSite, flowsFor, slugify, stoppedAtSignIn } from "./site-discovery.js";
-import { discoveryUrl, runDiscoveryTask } from "./discovery-task.js";
+import { discoverableRoute, discoverSite, discoveryLimitsFromEnv, flowsFor, slugify, stoppedAtSignIn } from "./site-discovery.js";
+import { discoveryUrl, progressOf, runDiscoveryTask } from "./discovery-task.js";
 import { PlaywrightDriver } from "./playwright-driver.js";
 import { startLocalRegistryStub } from "./local-registry-stub.js";
 import { ControlPlaneClient } from "../registry/control-plane-client.js";
 
 const pages: Record<string, string> = {
-  "/": `<title>Acme</title><nav><a href="/pricing">Pricing</a> <a href="/signup">Sign up</a> <a href="/logout">Log out</a> <a href="https://elsewhere.example/">Blog</a></nav><h1>Welcome to Acme</h1>`,
+  "/": `<title>Acme</title><nav><a href="/pricing">Pricing</a> <a href="/signup">Sign up</a> <a href="/logout">Log out</a> <a href="https://elsewhere.example/">Blog</a> </nav><h1>Welcome to Acme</h1>`,
   "/pricing": `<title>Pricing · Acme</title><a href="/">Home</a><h1>Plans for every team</h1>`,
-  "/signup": `<title>Sign up · Acme</title><h1>Create your account</h1>
+  "/signup": `<title>Sign up · Acme</title><h1>Create your account</h1><a href="/">Home</a> <a href="/logout">Log out</a> <a href="/api/export">Export</a> <a href="/report.csv" download>Download report</a> <a href="/data">Raw data</a>
 <form aria-label="Registration"><label>Email <input type="email" required></label><label>Password <input type="password" required></label><button type="submit">Create account</button></form>`,
   "/logout": `<title>Bye</title><h1>You are signed out</h1>`,
 };
@@ -24,6 +24,11 @@ async function withSite(run: (baseUrl: string, hits: string[]) => Promise<void>)
   const server = http.createServer((request, response) => {
     const route = new URL(request.url ?? "/", "http://x").pathname;
     hits.push(route);
+    if (route === "/data" || route === "/api/export" || route === "/report.csv") {
+      response.writeHead(200, { "content-type": route === "/report.csv" ? "text/csv" : "application/json" });
+      response.end(route === "/report.csv" ? "a,b\n" : JSON.stringify({ rows: [] }));
+      return;
+    }
     const body = pages[route];
     response.writeHead(body ? 200 : 404, { "content-type": "text/html" });
     response.end(`<!doctype html><html><body>${body ?? "Not found"}</body></html>`);
@@ -86,6 +91,10 @@ test("explores a site from its URL like a visitor, and the flows it writes pass"
     const result = await discoverSite(baseUrl, { dwellMs: 0, onEvent: (event) => { events.push(event.text); } });
     assert.deepEqual(result.pages.map((page) => page.route).sort(), ["/", "/pricing", "/signup"]);
     assert.ok(!hits.includes("/logout"), "never opens a sign-out link");
+    assert.ok(!hits.includes("/api/export") && !hits.includes("/report.csv"), "never opens an API or download link");
+    assert.ok(events.some((text) => text.startsWith("Skipping “Export” (it downloads a file or calls the API)")));
+    assert.ok(events.some((text) => /“Raw data” opens a file \(application\/json\), not a page/.test(text)), "a link that opens JSON isn't a page");
+    assert.equal(events.filter((text) => text.startsWith("Skipping “Log out”")).length, 1, "a skipped link is reported once, not on every page that has it");
     assert.ok(events.includes("Visiting home page"));
     assert.ok(events.includes("Clicking “Pricing”"));
     assert.ok(events.some((text) => text.startsWith("Skipping “Log out”")));
@@ -118,6 +127,40 @@ test("explores a site from its URL like a visitor, and the flows it writes pass"
   });
 });
 
+test("a crawl cut short by its limits says which linked pages it never opened", async (t) => {
+  if (!(await chromiumInstalled())) {
+    t.skip("Chromium is not installed");
+    return;
+  }
+  await withSite(async (baseUrl) => {
+    const events: Array<{ kind: string; text: string }> = [];
+    const capped = await discoverSite(baseUrl, { dwellMs: 0, maxPages: 2, onEvent: (event) => { events.push(event); } });
+    assert.equal(capped.pages.length, 2);
+    assert.equal(capped.limits?.maxPages, 2);
+    assert.equal(capped.limits?.stoppedAtPageLimit, true);
+    assert.equal(capped.limits?.notFollowed.length, 1);
+    assert.ok(!capped.pages.some((page) => page.route === capped.limits?.notFollowed[0]));
+    assert.match(events.find((event) => event.kind === "limit")?.text ?? "", /Stopped at the 2-page limit; 1 linked page was not opened/);
+    const progress = progressOf(baseUrl, capped);
+    assert.equal(progress.limits?.notFollowed, 1);
+    assert.deepEqual(progress.limits?.notFollowedRoutes, capped.limits?.notFollowed);
+
+    const shallow = await discoverSite(baseUrl, { dwellMs: 0, maxDepth: 0 });
+    assert.deepEqual(shallow.pages.map((page) => page.route), ["/"]);
+    assert.equal(shallow.limits?.stoppedAtPageLimit, false);
+    assert.deepEqual([...(shallow.limits?.notFollowed ?? [])].sort(), ["/pricing", "/signup"]);
+
+    const whole = await discoverSite(baseUrl, { dwellMs: 0 });
+    assert.deepEqual(whole.limits, { maxPages: 12, maxDepth: 2, stoppedAtPageLimit: false, notFollowed: [] });
+  });
+});
+
+test("a project's own worker reads its exploration limits from the environment", () => {
+  assert.deepEqual(discoveryLimitsFromEnv({ BUGMOLE_DISCOVERY_MAX_PAGES: "60", BUGMOLE_DISCOVERY_MAX_DEPTH: "4" }), { maxPages: 60, maxDepth: 4 });
+  assert.deepEqual(discoveryLimitsFromEnv({ BUGMOLE_DISCOVERY_MAX_PAGES: "0", BUGMOLE_DISCOVERY_MAX_DEPTH: "two" }), {});
+  assert.deepEqual(discoveryLimitsFromEnv({}), {});
+});
+
 test("explores a signed-in app from a saved session, and stays inside it", async (t) => {
   if (!(await chromiumInstalled())) {
     t.skip("Chromium is not installed");