@bugmole/cli 0.4.0 → 0.6.0

package/src/registry-worker/task-resume.test.ts

@@ -0,0 +1,196 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { call, createTestEnv, seedProject, seedVerifiedDomain } from "./testing/harness.js";
+import { runnerLauncher, type LaunchRequest } from "./runner/dispatch.js";
+
+const CLOUD = { RUNNER_TOKEN_SECRET: "runner-test-secret", FEATURE_CLOUD_RUNNERS: "on", REGISTRY_PUBLIC_URL: "https://registry.test" };
+const VERIFIED = { "x-aegis-email": "owner@acme.test", "x-aegis-email-verified": "true" };
+
+function fakeLauncher() {
+  const launches: LaunchRequest[] = [];
+  const original = runnerLauncher.start;
+  runnerLauncher.start = async (_env, launch) => {
+    launches.push(launch);
+  };
+  return { launches, restore: () => { runnerLauncher.start = original; } };
+}
+
+/** A project on Bugmole storage (it runs in the cloud) or on the customer's own storage. */
+async function project(storage: "managed" | "byo") {
+  const setup = createTestEnv(CLOUD);
+  const seeded = await seedProject(setup.env, { storageProvider: storage === "managed" ? "bugmole" : "r2" });
+  seedVerifiedDomain(setup.db, seeded.workspaceId, "shop.test");
+  const { env, db } = setup;
+  const { owner, projectId } = seeded;
+  let key = 0;
+  const api = {
+    create: (taskType: string, extra: Record<string, unknown> = {}) => call(env, "POST", `/api/projects/${projectId}/tasks`, {
+      as: owner,
+      headers: VERIFIED,
+      body: { title: `A ${taskType} task`, description: "Explore https://shop.test", taskType, idempotencyKey: `k${key += 1}`, ...extra },
+    }),
+    resume: (taskId: string, body: Record<string, unknown> = {}) => call(env, "POST", `/api/tasks/${taskId}/resume`, { as: owner, headers: VERIFIED, body }),
+    approve: (taskId: string) => call(env, "POST", `/api/tasks/${taskId}/approve`, { as: owner }),
+    setMode: (taskApprovalMode: string) => call(env, "PATCH", `/api/projects/${projectId}/settings`, { as: owner, body: { taskApprovalMode } }),
+    /** Parks a task the way a worker that gave up (or the dispatcher) leaves it. */
+    park: (taskId: string, status = "blocked") => {
+      db.db.prepare("UPDATE agent_tasks SET status = ?, attempts = 3, error_message = 'gave up' WHERE id = ?").run(status, taskId);
+    },
+    /** A `bugmole serve` on someone's machine polling the task list with its API key. */
+    machinePolls: async () => {
+      const created = await call(env, "POST", "/api/api-keys", { as: owner, body: { name: "laptop", projectIds: [projectId] } });
+      assert.equal(created.status, 201, JSON.stringify(created.json));
+      const listed = await call(env, "GET", `/api/projects/${projectId}/tasks`, { token: created.json.token });
+      assert.equal(listed.status, 200);
+    },
+    row: (taskId: string) => db.db.prepare("SELECT status, execution_mode AS executionMode, approved_at AS approvedAt, approved_by AS approvedBy FROM agent_tasks WHERE id = ?").get(taskId) as Record<string, unknown>,
+  };
+  return { ...setup, ...seeded, api };
+}
+
+test("resuming a machine-only task on a cloud project with no machine connected is refused, and says what to do", async () => {
+  const { env, owner, projectId, api } = await project("managed");
+  const investigation = (await api.create("investigation")).json.task;
+  api.park(investigation.id);
+
+  const refused = await api.resume(investigation.id);
+  assert.equal(refused.status, 409);
+  assert.equal(refused.json.code, "needs_local_worker");
+  assert.equal(refused.json.canRunInCloud, false, "only discovery can run on Bugmole Cloud");
+  assert.match(refused.json.error, /npx bugmole serve/);
+  assert.equal(api.row(investigation.id).status, "blocked", "not silently queued");
+
+  // The dashboard's own reads don't count as a machine.
+  const dashboardList = await call(env, "GET", `/api/projects/${projectId}/tasks`, { as: owner });
+  assert.equal(dashboardList.json.localWorkerSeenAt, null);
+  assert.equal((await api.resume(investigation.id)).status, 409);
+
+  await api.machinePolls();
+  const listed = await call(env, "GET", `/api/projects/${projectId}/tasks`, { as: owner });
+  assert.ok(listed.json.localWorkerSeenAt, "the dashboard can see a machine is connected");
+  const resumed = await api.resume(investigation.id);
+  assert.equal(resumed.status, 200, JSON.stringify(resumed.json));
+  assert.equal(resumed.json.task.status, "queued");
+  assert.equal(resumed.json.task.attempts, 0);
+});
+
+test("a machine-only discovery on a cloud project can be resumed on Bugmole Cloud, which starts it straight away", async () => {
+  const launcher = fakeLauncher();
+  try {
+    const { api } = await project("managed");
+    const discovery = (await api.create("discovery")).json.task;
+    assert.equal(discovery.executionMode, "self");
+    api.park(discovery.id, "error");
+
+    const refused = await api.resume(discovery.id);
+    assert.equal(refused.status, 409);
+    assert.equal(refused.json.canRunInCloud, true);
+    assert.match(refused.json.error, /Bugmole Cloud/);
+
+    assert.equal((await api.resume(discovery.id, { executionMode: "self" })).status, 409, "asking for the machine again changes nothing");
+    assert.equal((await api.resume(discovery.id, { executionMode: "elsewhere" })).status, 422);
+
+    const moved = await api.resume(discovery.id, { executionMode: "cloud" });
+    assert.equal(moved.status, 200, JSON.stringify(moved.json));
+    assert.equal(moved.json.task.executionMode, "cloud");
+    assert.deepEqual(launcher.launches.map((launch) => [launch.kind, launch.id]), [["task", discovery.id]], "handed to the dispatcher on resume");
+    assert.equal(api.row(discovery.id).status, "running");
+  } finally {
+    launcher.restore();
+  }
+});
+
+test("only discovery can be moved to Bugmole Cloud", async () => {
+  const { api } = await project("managed");
+  const code = (await api.create("investigation")).json.task;
+  api.park(code.id);
+  const moved = await api.resume(code.id, { executionMode: "cloud" });
+  assert.equal(moved.status, 422);
+  assert.match(moved.json.error, /Only discovery/);
+});
+
+test("a cloud task that failed is dispatched again as soon as it's resumed", async () => {
+  const launcher = fakeLauncher();
+  try {
+    const { db, api } = await project("managed");
+    const discovery = (await api.create("discovery", { executionMode: "cloud" })).json.task;
+    assert.equal(launcher.launches.length, 1);
+    // The runner died and the dispatcher failed it, after pushing its next try out.
+    db.db.prepare(`
+      UPDATE agent_tasks SET status = 'error', lease_expires_at = NULL, dispatch_attempts = 3,
+        next_dispatch_at = ?, billed_at = CURRENT_TIMESTAMP, billed_minutes = 2 WHERE id = ?
+    `).run(new Date(Date.now() + 3_600_000).toISOString(), discovery.id);
+
+    const resumed = await api.resume(discovery.id);
+    assert.equal(resumed.status, 200, JSON.stringify(resumed.json));
+    assert.equal(launcher.launches.length, 2, "not left for the next cron tick");
+    const row = db.db.prepare("SELECT status, billed_at AS billedAt, dispatch_attempts AS dispatchAttempts FROM agent_tasks WHERE id = ?").get(discovery.id) as Record<string, unknown>;
+    assert.equal(row.status, "running");
+    assert.equal(row.billedAt, null, "the new attempt is metered on its own");
+    assert.equal(row.dispatchAttempts, 1);
+  } finally {
+    launcher.restore();
+  }
+});
+
+test("on a project that keeps its work on a machine, resume still queues ahead of `bugmole serve`", async () => {
+  const { api } = await project("byo");
+  const investigation = (await api.create("investigation")).json.task;
+  api.park(investigation.id);
+  const resumed = await api.resume(investigation.id);
+  assert.equal(resumed.status, 200, JSON.stringify(resumed.json));
+  assert.equal(resumed.json.task.status, "queued");
+});
+
+test("resume keeps a person's approval, and lets the project's current mode decide an automatic one", async () => {
+  const launcher = fakeLauncher();
+  try {
+    const { owner, api } = await project("byo");
+    const code = (await api.create("code")).json.task;
+    assert.equal(code.approvedAt, null);
+    assert.equal((await api.approve(code.id)).status, 200);
+    const investigation = (await api.create("investigation")).json.task;
+    assert.equal(investigation.approvedBy, "auto:auto");
+    api.park(code.id);
+    api.park(investigation.id);
+
+    assert.equal((await api.setMode("manual")).status, 200);
+    const resumedCode = await api.resume(code.id);
+    assert.equal(resumedCode.json.task.approvedBy, owner, "a person already said yes");
+    assert.ok(resumedCode.json.task.approvedAt);
+
+    const resumedInvestigation = await api.resume(investigation.id);
+    assert.equal(resumedInvestigation.status, 200);
+    assert.equal(resumedInvestigation.json.task.approvedAt, null, "manual mode now holds it for approval");
+    assert.equal(resumedInvestigation.json.task.status, "queued");
+    assert.equal((await api.approve(investigation.id)).status, 200);
+
+    assert.equal((await api.setMode("extreme")).status, 200);
+    const held = (await api.create("code")).json.task;
+    assert.equal(held.approvedBy, "auto:extreme");
+    api.park(held.id);
+    assert.equal((await api.setMode("auto")).status, 200);
+    assert.equal((await api.resume(held.id)).json.task.approvedAt, null, "auto mode holds code changes again");
+  } finally {
+    launcher.restore();
+  }
+});
+
+test("a cloud discovery resumed into waiting for approval isn't dispatched until someone approves it", async () => {
+  const launcher = fakeLauncher();
+  try {
+    const { api } = await project("managed");
+    const discovery = (await api.create("discovery", { executionMode: "cloud" })).json.task;
+    assert.equal(launcher.launches.length, 1);
+    api.park(discovery.id, "error");
+    assert.equal((await api.setMode("manual")).status, 200);
+    const resumed = await api.resume(discovery.id);
+    assert.equal(resumed.status, 200);
+    assert.equal(resumed.json.task.approvedAt, null);
+    assert.equal(launcher.launches.length, 1, "waits for approval");
+    assert.equal((await api.approve(discovery.id)).status, 200);
+    assert.equal(launcher.launches.length, 2);
+  } finally {
+    launcher.restore();
+  }
+});

package/src/registry-worker/task-review.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { call, createTestEnv, seedProject } from "./testing/harness.js";
+
+async function inviteAndJoin(env: Parameters<typeof call>[0], inviter: string, workspaceId: string, who: string, role: string) {
+  const invited = await call(env, "POST", `/api/workspaces/${workspaceId}/invitations`, { as: inviter, body: { email: `${who}@example.com`, role } });
+  assert.equal(invited.status, 201, JSON.stringify(invited.json));
+  const token = invited.json.invitation.acceptUrl.split("/invite/")[1];
+  assert.equal((await call(env, "POST", `/api/invitations/${token}/accept`, { as: who })).status, 200);
+}
+
+async function setup(mode: string) {
+  const { env, db } = createTestEnv();
+  const { owner, workspaceId, projectId } = await seedProject(env);
+  assert.equal((await call(env, "PATCH", `/api/projects/${projectId}/settings`, { as: owner, body: { taskApprovalMode: mode } })).status, 200);
+  const key = await call(env, "POST", "/api/api-keys", { as: owner, body: { name: "laptop", projectIds: [projectId] } });
+  assert.equal(key.status, 201, JSON.stringify(key.json));
+  const token: string = key.json.token;
+  let n = 0;
+  const api = {
+    create: async (taskType: string) => {
+      const created = await call(env, "POST", `/api/projects/${projectId}/tasks`, {
+        as: owner, body: { title: `A ${taskType} task`, description: "Do the thing on https://shop.test", taskType, idempotencyKey: `k${n += 1}` },
+      });
+      assert.ok([200, 201].includes(created.status), JSON.stringify(created.json));
+      const task = created.json.task;
+      if (task.approvedAt === null) assert.equal((await call(env, "POST", `/api/tasks/${task.id}/approve`, { as: owner })).status, 200);
+      assert.equal((await call(env, "POST", `/api/tasks/${task.id}/claim`, { token, body: { workerId: "agent-1" } })).status, 200);
+      return task.id as string;
+    },
+    complete: (taskId: string, extra: Record<string, unknown> = {}) =>
+      call(env, "POST", `/api/tasks/${taskId}`, { token, body: { workerId: "agent-1", status: "completed", completionSummary: "Done", ...extra } }),
+    report: (taskId: string, status: string) => call(env, "POST", `/api/tasks/${taskId}`, { token, body: { workerId: "agent-1", status } }),
+    accept: (taskId: string, as: string | { token: string } = owner, body: unknown = {}) =>
+      call(env, "POST", `/api/tasks/${taskId}/accept`, typeof as === "string" ? { as, body } : { token: as.token, body }),
+    sendBack: (taskId: string, note: string, as = owner) => call(env, "POST", `/api/tasks/${taskId}/send-back`, { as, body: { note } }),
+  };
+  return { env, db, owner, workspaceId, projectId, token, api };
+}
+
+test("manual mode: every completed task goes to review, and a manager accepts it", async () => {
+  const { api, owner, db } = await setup("manual");
+  const taskId = await api.create("investigation");
+  const done = await api.complete(taskId);
+  assert.equal(done.status, 200, JSON.stringify(done.json));
+  assert.equal(done.json.task.status, "in_review");
+  assert.equal(done.json.inReview, true);
+  assert.match(done.json.message, /reviews this task/);
+  assert.equal(done.json.task.completedAt, null, "not completed until someone accepts it");
+
+  // Reporting completed again is a no-op; anything else is refused.
+  const again = await api.complete(taskId);
+  assert.equal(again.status, 200);
+  assert.equal(again.json.inReview, true);
+  assert.equal((await api.report(taskId, "running")).status, 409, "a heartbeat can't pull it out of review");
+
+  const accepted = await api.accept(taskId, owner, { note: "Looks right" });
+  assert.equal(accepted.status, 200, JSON.stringify(accepted.json));
+  assert.equal(accepted.json.task.status, "completed");
+  assert.equal(accepted.json.task.reviewedBy, owner);
+  assert.ok(accepted.json.task.reviewedAt);
+  assert.ok(accepted.json.task.completedAt);
+  assert.equal((await api.accept(taskId)).status, 409, "accepting twice");
+
+  const audit = db.db.prepare("SELECT action FROM audit_log WHERE target_id = ? ORDER BY rowid").all(taskId) as Array<{ action: string }>;
+  assert.ok(audit.some((row) => row.action === "task.review_accepted"), JSON.stringify(audit));
+});
+
+test("auto mode reviews code and ui tasks only; extreme reviews nothing", async () => {
+  const auto = await setup("auto");
+  const investigation = await auto.api.create("investigation");
+  assert.equal((await auto.api.complete(investigation)).json.task.status, "completed");
+  const code = await auto.api.create("code");
+  assert.equal((await auto.api.complete(code)).json.task.status, "in_review");
+  const ui = await auto.api.create("ui");
+  assert.equal((await auto.api.complete(ui, { parityAuditId: "audit-1", parityMatchScore: 97 })).json.task.status, "in_review");
+
+  const extreme = await setup("extreme");
+  const extremeCode = await extreme.api.create("code");
+  const done = await extreme.api.complete(extremeCode);
+  assert.equal(done.json.task.status, "completed");
+  assert.equal(done.json.inReview, undefined);
+});
+
+test("sending back queues the task again with the note, keeping its approval", async () => {
+  const { api, owner } = await setup("manual");
+  const taskId = await api.create("code");
+  await api.complete(taskId);
+  assert.equal((await api.sendBack(taskId, "  ")).status, 422, "a note is required");
+  const sent = await api.sendBack(taskId, "The button still overlaps the header on mobile.");
+  assert.equal(sent.status, 200, JSON.stringify(sent.json));
+  assert.equal(sent.json.task.status, "queued");
+  assert.equal(sent.json.task.reviewNote, "The button still overlaps the header on mobile.");
+  assert.match(sent.json.task.progressMessage, /Sent back from review/);
+  assert.equal(sent.json.task.approvedBy, owner, "the person's approval stands");
+  assert.equal(sent.json.task.workerId, null);
+  assert.equal(sent.json.task.attempts, 0);
+  assert.equal((await api.sendBack(taskId, "again")).status, 409, "only a task in review can be sent back");
+});
+
+test("only a person who manages the project reviews: not a member, not an API key", async () => {
+  const { env, api, token, workspaceId, owner } = await setup("manual");
+  await inviteAndJoin(env, owner, workspaceId, "user_member", "member");
+  const taskId = await api.create("code");
+  await api.complete(taskId);
+  assert.equal((await api.accept(taskId, "user_member")).status, 403);
+  assert.equal((await api.sendBack(taskId, "no", "user_member")).status, 403);
+  const byKey = await api.accept(taskId, { token });
+  assert.equal(byKey.status, 403, "an agent can't accept its own work");
+  assert.match(byKey.json.error, /person/);
+  assert.equal((await api.accept(taskId, "user_stranger")).status, 404);
+});
+
+test("a task in review can't be resumed; send it back instead", async () => {
+  const { env, api, owner } = await setup("manual");
+  const taskId = await api.create("code");
+  await api.complete(taskId);
+  const resumed = await call(env, "POST", `/api/tasks/${taskId}/resume`, { as: owner, body: {} });
+  assert.equal(resumed.status, 409);
+  assert.match(resumed.json.error, /review/);
+});

package/src/runtime/ai-exploration.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { explorationPrompt, parseExploration } from "./ai-exploration.js";
+import { explorationPrompt, parseCheckedExploration, parseExploration } from "./ai-exploration.js";
 import type { DiscoveryResult } from "./site-discovery.js";
 
 const result: DiscoveryResult = {
@@ -30,3 +30,36 @@ test("parseExploration only accepts well-formed journeys with at least two steps
   assert.equal(flows[0].name, "Sign up then buy");
   assert.equal(flows[0].kind, "journey");
 });
+
+// The real case that prompted the check: app.bugmole.com's sign-in page has one
+// button and no links, and the model wrote journeys through a "Forgot
+// password?" link and a sign-up page that don't exist.
+const signInOnly: DiscoveryResult = {
+  baseUrl: "https://app.test",
+  pages: [{ route: "/login", url: "https://app.test/login", title: "Bugmole", heading: "Welcome back", path: [], links: [], forms: [], controls: ["Continue with Aegis →"] }],
+  flows: [],
+  events: [],
+};
+
+test("the prompt shows the buttons discovery saw, and forbids inventing others", () => {
+  const prompt = explorationPrompt(signInOnly);
+  assert.match(prompt, /"buttons":\["Continue with Aegis →"\]/);
+  assert.match(prompt, /Never invent a page, link or button/);
+});
+
+test("journeys through controls or pages discovery never saw are set aside with the reason", () => {
+  const reply = JSON.stringify({
+    journeys: [
+      { name: "Forgot password", steps: [{ openLink: "/login" }, { tapOn: "Forgot password?" }, { assertVisible: "Reset your password" }] },
+      { name: "Sign up", steps: [{ openLink: "/signup" }, { assertVisible: "Create account" }] },
+      { name: "Hidden check", steps: [{ openLink: "/login" }, { assertVisible: "Remember me" }, { tapOn: "Continue with Aegis" }] },
+      { name: "Continue to Aegis", steps: [{ openLink: "/login" }, { assertVisible: "Welcome back" }, { tapOn: "Continue with Aegis" }, { assertVisible: "Sign in to Aegis" }] },
+    ],
+  });
+  const { flows, setAside } = parseCheckedExploration(reply, signInOnly);
+  assert.deepEqual(flows.map((flow) => flow.name), ["Continue to Aegis"], "the last assertion may be new text: it is the outcome");
+  assert.deepEqual(setAside.map((item) => item.name), ["Forgot password", "Sign up", "Hidden check"]);
+  assert.match(setAside[0].reason, /taps “Forgot password\?”/);
+  assert.match(setAside[1].reason, /opens \/signup/);
+  assert.match(setAside[2].reason, /expects “Remember me”/);
+});

package/src/runtime/ai-exploration.ts

@@ -4,7 +4,7 @@
 import YAML from "yaml";
 import { parseMaestroStyleFlow } from "./flow-language.js";
 import { extractJson } from "./platform-ai.js";
-import { slugify, type DiscoveredFlow, type DiscoveryResult } from "./site-discovery.js";
+import { slugify, type DiscoveredFlow, type DiscoveredPage, type DiscoveryResult } from "./site-discovery.js";
 
 const MAX_JOURNEYS = 8;
 const MAX_STEPS = 40;
@@ -19,12 +19,13 @@ export function explorationPrompt(result: DiscoveryResult, persona?: Exploration
     reachedBy: page.path,
     links: page.links.slice(0, 15).map((link) => link.label),
     forms: page.forms.map((form) => ({ name: form.name, fields: form.fields.map((field) => `${field.label} (${field.type}${field.required ? ", required" : ""})`), submit: form.submit })),
+    ...(page.controls?.length ? { buttons: page.controls.slice(0, 20) } : {}),
   }));
   return [
     "You are a QA engineer. Below is a map of a web app a crawler just explored.",
     ...(persona ? [`Decide what's worth testing from this persona's point of view — ${persona.name}: ${persona.description}`] : []),
     `Write up to ${MAX_JOURNEYS} end-to-end user journeys worth testing that span several pages (for example: sign up, then buy something).`,
-    "Only use pages, links, buttons and fields that appear in the map. Don't repeat single-page visits; those already exist.",
+    "Only use pages, links, buttons and fields that appear in the map, with their exact text. Never invent a page, link or button; if the map is too small for a journey, return fewer journeys or none. Don't repeat single-page visits; those already exist.",
     "Use obvious sample data (qa@example.com, Bugmole). Write passwords as \"{{secret.APP_PASSWORD}}\". Never submit destructive actions (delete, cancel, unsubscribe).",
     "Steps: openLink: \"/path\"; tapOn: \"<visible text>\"; inputText: \"<text>\"; assertVisible: \"<text>\"; scrollUntilVisible: { element: \"<text>\" }.",
     "Every journey starts with openLink and ends with an assertVisible that proves it worked.",
@@ -35,7 +36,99 @@ export function explorationPrompt(result: DiscoveryResult, persona?: Exploration
   ].join("\n");
 }
 
-export function parseExploration(reply: string, baseUrl: string, existing: readonly DiscoveredFlow[]): DiscoveredFlow[] {
+const normalize = (value: string) => value.toLowerCase().replace(/\s+/g, " ").replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+
+/**
+ * Everything a visitor could see or type into on the explored pages, and the
+ * routes that exist. A journey step outside this is something the model made
+ * up, however plausible ("Forgot password?" on a page that has no such link).
+ */
+function observedOn(pages: readonly DiscoveredPage[], baseUrl: string) {
+  const words = new Set<string>();
+  const add = (value?: string) => {
+    const normal = value ? normalize(value) : "";
+    if (normal) words.add(normal);
+  };
+  const routes = new Set<string>(["/"]);
+  for (const page of pages) {
+    routes.add(page.route);
+    add(page.title);
+    add(page.heading);
+    for (const link of page.links) {
+      add(link.label);
+      add(link.menu);
+      routes.add(link.route);
+    }
+    for (const form of page.forms) {
+      add(form.name);
+      add(form.submit);
+      for (const field of form.fields) add(field.label);
+    }
+    for (const control of page.controls ?? []) add(control);
+  }
+  const seen = (text: string) => {
+    const target = normalize(text);
+    if (!target) return false;
+    for (const word of words) {
+      if (word === target || (target.length >= 3 && word.includes(target)) || (word.length >= 3 && target.includes(word))) return true;
+    }
+    return false;
+  };
+  const routeExists = (link: string) => {
+    try {
+      const url = new URL(link, baseUrl);
+      if (url.origin !== new URL(baseUrl).origin) return false;
+      return routes.has(url.pathname) || routes.has(url.pathname.replace(/\/$/, "") || "/");
+    } catch {
+      return false;
+    }
+  };
+  return { seen, routeExists };
+}
+
+/**
+ * Why a journey can't be trusted, or null. Taps, scrolls and assertions along
+ * the way must name something observed, and every openLink a real route. The
+ * last assertVisible may name new text: it is the outcome the journey proves
+ * (a confirmation after a form), which discovery, being read-only, never saw.
+ */
+function unobservedStep(steps: readonly unknown[], observed: ReturnType<typeof observedOn>): string | null {
+  for (const [index, raw] of steps.entries()) {
+    const step = raw as Record<string, unknown>;
+    if (typeof step?.openLink === "string" && !observed.routeExists(step.openLink)) return `opens ${step.openLink}, which wasn't found`;
+    const tap = typeof step?.tapOn === "string" ? step.tapOn : undefined;
+    if (tap && !observed.seen(tap)) return `taps “${tap}”, which isn't on any explored page`;
+    const scroll = (step?.scrollUntilVisible as { element?: unknown } | undefined)?.element;
+    if (typeof scroll === "string" && !observed.seen(scroll)) return `looks for “${scroll}”, which isn't on any explored page`;
+    const assertion = typeof step?.assertVisible === "string" ? step.assertVisible : undefined;
+    if (assertion && index < steps.length - 1 && !observed.seen(assertion)) return `expects “${assertion}”, which isn't on any explored page`;
+  }
+  return null;
+}
+
+export type CheckedExploration = { flows: DiscoveredFlow[]; setAside: Array<{ name: string; reason: string }> };
+
+/**
+ * Parses the model's journeys and keeps only those built from what discovery
+ * actually saw on `pages`; the rest are set aside with the reason.
+ */
+export function parseCheckedExploration(reply: string, result: Pick<DiscoveryResult, "baseUrl" | "pages" | "flows">): CheckedExploration {
+  const observed = observedOn(result.pages, result.baseUrl);
+  const setAside: CheckedExploration["setAside"] = [];
+  const flows = parseExploration(reply, result.baseUrl, result.flows, (name, steps) => {
+    const reason = unobservedStep(steps, observed);
+    if (reason) setAside.push({ name, reason });
+    return !reason;
+  });
+  return { flows, setAside };
+}
+
+export function parseExploration(
+  reply: string,
+  baseUrl: string,
+  existing: readonly DiscoveredFlow[],
+  accept: (name: string, steps: readonly unknown[]) => boolean = () => true,
+): DiscoveredFlow[] {
   const data = extractJson(reply) as { journeys?: unknown } | null;
   if (!data || !Array.isArray(data.journeys)) return [];
   const taken = new Set(existing.map((flow) => flow.id));
@@ -44,6 +137,7 @@ export function parseExploration(reply: string, baseUrl: string, existing: reado
     const name = typeof journey?.name === "string" ? journey.name.trim().slice(0, 80) : "";
     const steps = Array.isArray(journey?.steps) ? journey.steps.slice(0, MAX_STEPS) : [];
     if (!name || steps.length < 2) continue;
+    if (!accept(name, steps)) continue;
     const content = `url: ${baseUrl}\nname: ${JSON.stringify(name)}\n---\n${YAML.stringify(steps)}`;
     let parsed;
     try {

package/src/runtime/appium-driver.ts

@@ -124,7 +124,7 @@ export class AppiumDriver implements AppDriver {
         for (const rawStep of list) {
           const index = counter.n++;
           const began = Date.now();
-          const step = interpolateStep(rawStep, flowContext);
+          const step = interpolateStep(rawStep, flowContext, { env: { ...process.env, ...context.environment } });
           try {
             if (step.type === "retry") {
               let lastError: unknown;
@@ -139,6 +139,12 @@ export class AppiumDriver implements AppDriver {
               }
               counter.n += step.steps.length;
               if (lastError) throw lastError;
+            } else if (step.type === "assertLayout" || step.type === "assertLinks") {
+              // Page checks read the page's layout and links, which a device
+              // cloud session doesn't expose; they run in the browser targets.
+              steps.push({ sequenceNumber: index, status: "passed", label: describeStepLabel(step), message: "Not checked on device clouds; checked in the browser targets", durationMs: 0 });
+              log.push(`Step ${index + 1}: ${describeStepForLog(step)} — skipped (checked in browsers, not on device clouds)`);
+              continue;
             } else {
               await this.step(session!, step, mode, flow, context, outDir, artifacts);
             }

package/src/runtime/apply-proposals.test.ts

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { ControlPlaneClient } from "../registry/control-plane-client.js";
+import { applyAcceptedProposals } from "./apply-proposals.js";
+import { startLocalRegistryStub } from "./local-registry-stub.js";
+
+const loginCase = (title: string) => ({
+  title, nodeId: "screen:/login", intent: "Prove a person can sign in.",
+  steps: ["Open /login", "Sign in"], expected: ["The dashboard opens"], confidence: "high", basis: ["spec"],
+});
+
+test("an accepted proposal is written to the project's own storage as a new revision, once", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-proposals-"));
+  const stub = await startLocalRegistryStub({ directory: path.join(directory, "registry") });
+  try {
+    const artifacts = path.join(directory, "artifacts");
+    const cfg = { project: { id: "demo" }, runtime: { spec_dir: path.join(directory, "spec"), artifacts_dir: artifacts }, storage: { provider: "local", localDirectory: artifacts } };
+    const setFile = path.join(artifacts, "projects", "demo", "test-cases", "login.json");
+    await fs.mkdir(path.dirname(setFile), { recursive: true });
+    await fs.writeFile(setFile, JSON.stringify({ schemaVersion: 1, caseSetId: "login", journeyId: "j", journeyRevision: 1, cases: [{ caseId: "TC-login", ...loginCase("Sign in works") }] }));
+
+    const client = new ControlPlaneClient({ registryUrl: stub.origin, apiKey: "local", projectId: "demo" });
+    const { proposal } = await client.proposeTestCaseChange({ caseSetId: "login", caseId: "TC-login", action: "change", baseRevision: 1, case: loginCase("Sign in with a password works"), summary: "Name the path", source: "cli" });
+    assert.equal(proposal.status, "accepted");
+
+    const first = await applyAcceptedProposals(cfg, client);
+    assert.deepEqual(first.map((item) => item.outcome), ["applied"]);
+    const stored = JSON.parse(await fs.readFile(setFile, "utf8"));
+    assert.deepEqual(stored.cases.map((item: { revision?: number; status?: string; title: string }) => [item.revision ?? 1, item.status ?? "active", item.title]), [
+      [1, "obsolete", "Sign in works"],
+      [2, "active", "Sign in with a password works"],
+    ]);
+    assert.deepEqual(await applyAcceptedProposals(cfg, client), [], "applied proposals aren't applied again");
+
+    await client.proposeTestCaseChange({ caseSetId: "login", caseId: "TC-login", action: "retire", baseRevision: 1, summary: "Stale", source: "cli" });
+    const stale = await applyAcceptedProposals(cfg, client);
+    assert.equal(stale[0].outcome, "outdated", "retiring revision 1 after revision 2 exists");
+  } finally {
+    await stub.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("bugmole propose reads the revision being changed from storage and refuses a bad file before sending anything", async () => {
+  const { proposeFromFile } = await import("./propose-cli.js");
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-propose-cli-"));
+  const stub = await startLocalRegistryStub({ directory: path.join(directory, "registry") });
+  try {
+    const artifacts = path.join(directory, "artifacts");
+    const cfg = { project: { id: "demo" }, runtime: { artifacts_dir: artifacts }, storage: { provider: "local", localDirectory: artifacts } };
+    const setFile = path.join(artifacts, "projects", "demo", "test-cases", "login.json");
+    await fs.mkdir(path.dirname(setFile), { recursive: true });
+    await fs.writeFile(setFile, JSON.stringify({ schemaVersion: 1, caseSetId: "login", journeyId: "j", journeyRevision: 1, cases: [{ caseId: "TC-login", ...loginCase("Sign in works") }] }));
+    const client = new ControlPlaneClient({ registryUrl: stub.origin, apiKey: "local", projectId: "demo" });
+
+    const bad = path.join(directory, "bad.json");
+    await fs.writeFile(bad, JSON.stringify({ caseSetId: "login", summary: "x", changes: [{ caseId: "TC-login", action: "change", case: loginCase("ok") }, { caseId: "TC-nope", action: "retire" }] }));
+    await assert.rejects(proposeFromFile(cfg, bad, client), /change 2: TC-nope has no current revision/);
+    assert.equal((await client.listUnappliedProposals()).proposals.length, 0, "nothing was sent");
+
+    const good = path.join(directory, "good.json");
+    await fs.writeFile(good, JSON.stringify({ caseSetId: "login", summary: "Name the password path", changes: [{ caseId: "TC-login", action: "change", case: loginCase("Sign in with a password works") }] }));
+    const [proposal] = await proposeFromFile(cfg, good, client);
+    assert.equal(proposal.baseRevision, 1);
+    const stored = JSON.parse(await fs.readFile(setFile, "utf8"));
+    assert.equal(stored.cases.find((item: { status?: string }) => item.status === "active").revision, 2, "accepted on arrival locally and applied");
+  } finally {
+    await stub.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

package/src/runtime/apply-proposals.ts

@@ -0,0 +1,41 @@
+// Writes accepted proposals into a project's own storage. On Bugmole storage
+// the registry applies them itself; a project that keeps its files elsewhere
+// has them applied here, by `bugmole serve` or the CLI that proposed them.
+import type { ControlPlaneClient, RegistryProposal } from "../registry/control-plane-client.js";
+import { applyTestCaseChange, type CaseSetDocument, type RevisionedCase, type TestCaseChange } from "../registry/test-case-revisions.js";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+
+type Client = Pick<ControlPlaneClient, "listUnappliedProposals" | "reportProposalApplied">;
+
+export function changeFromProposal(proposal: RegistryProposal): TestCaseChange {
+  const proposed = { ...(proposal.proposed ?? {}), caseId: proposal.caseId } as RevisionedCase;
+  if (proposal.action === "add") return { action: "add", case: proposed };
+  if (proposal.action === "retire") return { action: "retire", caseId: proposal.caseId, baseRevision: proposal.baseRevision ?? 0 };
+  return { action: "change", caseId: proposal.caseId, baseRevision: proposal.baseRevision ?? 0, case: proposed };
+}
+
+/** Applies every accepted, unapplied proposal; returns what happened to each. */
+export async function applyAcceptedProposals(cfg: any, client: Client): Promise<Array<{ id: string; outcome: "applied" | "outdated"; detail: string }>> {
+  if (cfg.storage?.provider === "bugmole") return [];
+  const { proposals } = await client.listUnappliedProposals();
+  const store = createProjectObjectStore(cfg);
+  const projectId = cfg.project?.id ?? "default";
+  const done: Array<{ id: string; outcome: "applied" | "outdated"; detail: string }> = [];
+  for (const proposal of proposals) {
+    const key = `${projectPrefix(projectId)}/test-cases/${proposal.caseSetId}.json`;
+    const current = (await store.has(key)) ? JSON.parse(await store.getText(key)) as CaseSetDocument : null;
+    const outcome = current
+      ? applyTestCaseChange(current, changeFromProposal(proposal), { proposalId: proposal.id })
+      : { ok: false as const, reason: "missing" as const, message: `There's no case set ${proposal.caseSetId}` };
+    if (outcome.ok) {
+      await store.put(key, `${JSON.stringify(outcome.caseSet, null, 2)}\n`, "application/json");
+      await client.reportProposalApplied(proposal.id, { outcome: "applied", revision: outcome.revision });
+      done.push({ id: proposal.id, outcome: "applied", detail: `${proposal.caseId} revision ${outcome.revision}` });
+    } else {
+      await client.reportProposalApplied(proposal.id, { outcome: "outdated", message: outcome.message });
+      done.push({ id: proposal.id, outcome: "outdated", detail: outcome.message });
+    }
+  }
+  return done;
+}