@bugmole/cli 0.4.0

package/src/runtime/device-clouds/browserstack.ts

@@ -0,0 +1,73 @@
+// BrowserStack App Automate (native apps) and Automate (mobile browsers).
+import type { AppBuild, DeviceCredential, DeviceSessionHost } from "./types.js";
+
+const HUB = "https://hub.browserstack.com/wd/hub";
+const API = "https://api-cloud.browserstack.com";
+
+function basic(credential: DeviceCredential): string {
+  return `Basic ${btoa(`${credential.username}:${credential.secret}`)}`;
+}
+
+async function ensureApp(credential: DeviceCredential, app: AppBuild, doFetch: typeof fetch): Promise<string> {
+  // custom_id lets a second run reuse the upload instead of sending the file again.
+  const customId = `bugmole-${app.sha256.slice(0, 32)}`;
+  const recent = await doFetch(`${API}/app-automate/recent_apps/${customId}`, { headers: { authorization: basic(credential) } });
+  if (recent.ok) {
+    const apps = await recent.json().catch(() => []) as Array<{ app_url?: string }>;
+    if (Array.isArray(apps) && apps[0]?.app_url) return apps[0].app_url;
+  }
+  const form = new FormData();
+  form.set("file", new Blob([Buffer.from(await app.load())]), app.filename);
+  form.set("custom_id", customId);
+  const uploaded = await doFetch(`${API}/app-automate/upload`, { method: "POST", headers: { authorization: basic(credential) }, body: form });
+  const body = await uploaded.json().catch(() => ({})) as { app_url?: string; error?: string };
+  if (!uploaded.ok || !body.app_url) throw new Error(`BrowserStack didn't accept the app${body.error ? `: ${body.error}` : ""}`);
+  return body.app_url;
+}
+
+export function browserstackHost(credential: DeviceCredential, doFetch: typeof fetch = fetch): DeviceSessionHost {
+  return {
+    async open({ device, name, app }) {
+      const native = !device.browserName;
+      const appUrl = native && app ? await ensureApp(credential, app, doFetch) : undefined;
+      if (native && !appUrl) throw new Error("A native app run needs an uploaded app build");
+      const capabilities: Record<string, unknown> = {
+        platformName: device.platform === "android" ? "Android" : "iOS",
+        ...(device.browserName ? { browserName: device.browserName === "chrome" ? "Chrome" : "Safari" } : { "appium:app": appUrl }),
+        "bstack:options": {
+          userName: credential.username,
+          accessKey: credential.secret,
+          deviceName: device.deviceName,
+          ...(device.osVersion ? { osVersion: device.osVersion } : {}),
+          realMobile: String(device.real),
+          projectName: "Bugmole",
+          buildName: name.split(" · ")[0],
+          sessionName: name,
+          video: true,
+          networkLogs: true,
+        },
+      };
+      const api = native ? "app-automate" : "automate";
+      return {
+        hubUrl: HUB,
+        capabilities,
+        finish: async ({ passed, webdriverSessionId, reason }) => {
+          if (!webdriverSessionId) return { links: [] };
+          const url = `https://api.browserstack.com/${api}/sessions/${webdriverSessionId}.json`;
+          await doFetch(url, {
+            method: "PUT",
+            headers: { authorization: basic(credential), "content-type": "application/json" },
+            body: JSON.stringify({ status: passed ? "passed" : "failed", ...(reason ? { reason: reason.slice(0, 255) } : {}) }),
+          }).catch(() => undefined);
+          const details = await doFetch(url, { headers: { authorization: basic(credential) } }).then((reply) => reply.json()).catch(() => null) as
+            { automation_session?: { public_url?: string; video_url?: string } } | null;
+          const session = details?.automation_session;
+          return {
+            links: session?.public_url ? [{ label: "BrowserStack session", url: session.public_url }] : [],
+            ...(session?.video_url ? { videoUrl: session.video_url } : {}),
+          };
+        },
+      };
+    },
+  };
+}

package/src/runtime/device-clouds/device-farm.ts

@@ -0,0 +1,52 @@
+// AWS Device Farm with the customer's own account, through its managed
+// Appium endpoint. Bugmole's own device cloud uses the same calls from the
+// registry (see registryDeviceHost), so no AWS keys reach a runner.
+import { finishedSession, listDevices, sessionArtifacts, startSession, stopSession, uploadApp, type DeviceFarmOptions } from "../../integrations/device-farm.js";
+import type { CloudDevice, DeviceCredential, DeviceSessionHost } from "./types.js";
+
+export function deviceFarmCapabilities(device: CloudDevice): Record<string, unknown> {
+  // Device Farm rejects device-specific capabilities such as udid and platformVersion.
+  return {
+    platformName: device.platform === "android" ? "Android" : "iOS",
+    "appium:automationName": device.platform === "android" ? "UiAutomator2" : "XCUITest",
+    ...(device.browserName ? { browserName: device.browserName === "chrome" ? "Chrome" : "Safari" } : {}),
+  };
+}
+
+export async function resolveDeviceArn(options: DeviceFarmOptions, device: CloudDevice): Promise<string> {
+  if (device.deviceArn) return device.deviceArn;
+  const platform = device.platform === "android" ? "ANDROID" : "IOS";
+  const match = (await listDevices(options)).find((candidate) =>
+    candidate.platform === platform
+    && candidate.name.toLowerCase() === device.deviceName.toLowerCase()
+    && (!device.osVersion || candidate.os === device.osVersion));
+  if (!match) throw new Error(`Device Farm has no ${device.deviceName}${device.osVersion ? ` on ${device.osVersion}` : ""}`);
+  return match.arn;
+}
+
+export function deviceFarmHost(credential: DeviceCredential, doFetch: typeof fetch = fetch): DeviceSessionHost {
+  if (!credential.projectArn) throw new Error("The Device Farm connection has no project ARN");
+  const options: DeviceFarmOptions = {
+    credentials: { accessKeyId: credential.username, secretAccessKey: credential.secret },
+    projectArn: credential.projectArn,
+    fetch: doFetch,
+  };
+  return {
+    async open({ device, name, app }) {
+      const deviceArn = await resolveDeviceArn(options, device);
+      const appArn = !device.browserName && app ? await uploadApp(options, { name: app.filename, platform: app.platform, bytes: await app.load() }) : undefined;
+      if (!device.browserName && !appArn) throw new Error("A native app run needs an uploaded app build");
+      const session = await startSession(options, { deviceArn, name, appArn });
+      return {
+        hubUrl: session.remoteDriverEndpoint!,
+        capabilities: deviceFarmCapabilities(device),
+        finish: async () => {
+          await stopSession(options, session.arn).catch(() => undefined);
+          const done = await finishedSession(options, session.arn);
+          const video = (await sessionArtifacts(options, session.arn).catch(() => [])).find((artifact) => artifact.type === "VIDEO");
+          return { links: [], ...(video ? { videoUrl: video.url } : {}), ...(done.meteredMinutes !== undefined ? { meteredMinutes: done.meteredMinutes } : {}) };
+        },
+      };
+    },
+  };
+}

package/src/runtime/device-clouds/index.ts

@@ -0,0 +1,92 @@
+// Which host opens a session for a device target, and loading what a run
+// needs (the workspace's device-cloud credentials and app builds) from the
+// registry just before it starts.
+import { browserstackHost } from "./browserstack.js";
+import { deviceFarmHost } from "./device-farm.js";
+import { kobitonHost } from "./kobiton.js";
+import type { AppBuild, CloudDevice, DeviceCredential, DeviceSessionHost, SessionReport } from "./types.js";
+
+export * from "./types.js";
+
+export type DeviceCloudAccess = {
+  credentials: Record<string, DeviceCredential>;
+  appBuilds: Record<string, AppBuild>;
+  /** Bugmole's own device cloud, opened by the registry. */
+  bugmole?: DeviceSessionHost;
+};
+
+export function hostFor(access: DeviceCloudAccess | undefined, device: CloudDevice, doFetch: typeof fetch = fetch): DeviceSessionHost {
+  if (device.provider === "bugmole") {
+    if (!access?.bugmole) throw new Error("Bugmole's device cloud is only available to runs on Bugmole Cloud");
+    return access.bugmole;
+  }
+  const credential = device.credentialId ? access?.credentials[device.credentialId] : undefined;
+  if (!credential) throw new Error(`The ${device.provider} connection for this device isn't available to this worker`);
+  if (credential.provider === "browserstack") return browserstackHost(credential, doFetch);
+  if (credential.provider === "kobiton") return kobitonHost(credential, doFetch);
+  return deviceFarmHost(credential, doFetch);
+}
+
+type RegistryAccess = {
+  registryUrl: string;
+  token: string;
+  runId: string;
+  loadObject: (key: string) => Promise<Uint8Array>;
+  fetch?: typeof fetch;
+  pollMs?: number;
+  maxWaitMs?: number;
+};
+
+type AccessReply = {
+  credentials?: Record<string, DeviceCredential>;
+  appBuilds?: Array<{ id: string; platform: "android" | "ios"; filename: string; sha256: string; objectKey: string }>;
+  bugmole?: boolean;
+};
+
+/** Fetches the run's device access from the registry. Only what the run's own targets use is returned. */
+export async function loadDeviceCloudAccess(options: RegistryAccess): Promise<DeviceCloudAccess> {
+  const doFetch = options.fetch ?? fetch;
+  const base = `${options.registryUrl.replace(/\/$/, "")}/api/runs/${encodeURIComponent(options.runId)}`;
+  const headers = { authorization: `Bearer ${options.token}`, "content-type": "application/json" };
+  const reply = await doFetch(`${base}/device-access`, { headers });
+  const body = await reply.json().catch(() => ({})) as AccessReply & { error?: string };
+  if (!reply.ok) throw new Error(body.error ?? `The registry refused device access (${reply.status})`);
+  const appBuilds: Record<string, AppBuild> = {};
+  for (const build of body.appBuilds ?? []) {
+    appBuilds[build.id] = { id: build.id, platform: build.platform, filename: build.filename, sha256: build.sha256, load: () => options.loadObject(build.objectKey) };
+  }
+  const bugmole: DeviceSessionHost | undefined = body.bugmole ? {
+    async open({ device, name }) {
+      const opened = await doFetch(`${base}/device-sessions`, { method: "POST", headers, body: JSON.stringify({ device, name }) });
+      const session = await opened.json().catch(() => ({})) as { sessionId?: string; capabilities?: Record<string, unknown>; error?: string };
+      if (!opened.ok || !session.sessionId) throw new Error(session.error ?? `Bugmole's device cloud couldn't start a device (${opened.status})`);
+      // A real device takes a minute or two to become free and boot the Appium server.
+      const deadline = Date.now() + (options.maxWaitMs ?? 15 * 60_000);
+      let hubUrl: string | undefined;
+      for (;;) {
+        const polled = await doFetch(`${base}/device-sessions/${encodeURIComponent(session.sessionId)}`, { headers });
+        const state = await polled.json().catch(() => ({})) as { status?: string; hubUrl?: string; error?: string };
+        if (state.status === "running" && state.hubUrl) {
+          hubUrl = state.hubUrl;
+          break;
+        }
+        if (!polled.ok || state.status === "failed" || Date.now() > deadline) {
+          await doFetch(`${base}/device-sessions/${encodeURIComponent(session.sessionId)}/finish`, { method: "POST", headers, body: "{}" }).catch(() => undefined);
+          throw new Error(state.error ?? "No device became available in time");
+        }
+        await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? 5_000));
+      }
+      return {
+        hubUrl,
+        capabilities: session.capabilities ?? {},
+        finish: async (outcome) => {
+          const finished = await doFetch(`${base}/device-sessions/${encodeURIComponent(session.sessionId!)}/finish`, {
+            method: "POST", headers, body: JSON.stringify({ passed: outcome.passed }),
+          });
+          return (await finished.json().catch(() => ({ links: [] }))) as SessionReport;
+        },
+      };
+    },
+  } : undefined;
+  return { credentials: body.credentials ?? {}, appBuilds, ...(bugmole ? { bugmole } : {}) };
+}

package/src/runtime/device-clouds/kobiton.ts

@@ -0,0 +1,70 @@
+// Kobiton real and virtual devices.
+import type { AppBuild, DeviceCredential, DeviceSessionHost } from "./types.js";
+
+const HUB = "https://api.kobiton.com/wd/hub";
+const API = "https://api.kobiton.com/v1";
+
+function basic(credential: DeviceCredential): string {
+  return `Basic ${btoa(`${credential.username}:${credential.secret}`)}`;
+}
+
+async function uploadApp(credential: DeviceCredential, app: AppBuild, doFetch: typeof fetch): Promise<string> {
+  const headers = { authorization: basic(credential), "content-type": "application/json" };
+  const target = await doFetch(`${API}/apps/uploadUrl`, { method: "POST", headers, body: JSON.stringify({ filename: app.filename }) });
+  const slot = await target.json().catch(() => ({})) as { appPath?: string; url?: string };
+  if (!target.ok || !slot.url || !slot.appPath) throw new Error("Kobiton didn't provide an upload address");
+  const put = await doFetch(slot.url, {
+    method: "PUT",
+    headers: { "content-type": "application/octet-stream", "x-amz-tagging": "unsaved=true" },
+    body: await app.load() as BodyInit,
+  });
+  if (!put.ok) throw new Error(`Kobiton's storage refused the app (${put.status})`);
+  const created = await doFetch(`${API}/apps`, { method: "POST", headers, body: JSON.stringify({ filename: app.filename, appPath: slot.appPath }) });
+  const body = await created.json().catch(() => ({})) as { versionId?: number; appId?: number };
+  if (!created.ok || !body.versionId) throw new Error("Kobiton didn't register the app");
+  return `kobiton-store:v${body.versionId}`;
+}
+
+export function kobitonHost(credential: DeviceCredential, doFetch: typeof fetch = fetch): DeviceSessionHost {
+  return {
+    async open({ device, name, app }) {
+      const native = !device.browserName;
+      const appRef = native && app ? await uploadApp(credential, app, doFetch) : undefined;
+      if (native && !appRef) throw new Error("A native app run needs an uploaded app build");
+      const capabilities: Record<string, unknown> = {
+        platformName: device.platform === "android" ? "Android" : "iOS",
+        "appium:deviceName": device.deviceName,
+        ...(device.osVersion ? { "appium:platformVersion": device.osVersion } : {}),
+        "appium:automationName": device.platform === "android" ? "UiAutomator2" : "XCUITest",
+        ...(device.browserName ? { browserName: device.browserName } : { "appium:app": appRef }),
+        "kobiton:options": {
+          sessionName: name,
+          sessionDescription: "Bugmole test run",
+          deviceGroup: "KOBITON",
+          captureScreenshots: true,
+          deviceOrientation: "portrait",
+          ...(device.real ? {} : { useVirtualDevice: true }),
+        },
+      };
+      return {
+        hubUrl: HUB,
+        capabilities,
+        authorization: basic(credential),
+        finish: async ({ webdriverSessionId }) => {
+          if (!webdriverSessionId) return { links: [] };
+          // Kobiton names its own session id in the capabilities it returns; look it up by WebDriver id otherwise.
+          const lookup = await doFetch(`${API}/sessions?appiumSessionId=${encodeURIComponent(webdriverSessionId)}`, { headers: { authorization: basic(credential) } })
+            .then((reply) => reply.json()).catch(() => null) as { data?: Array<{ id: number }> } | null;
+          const id = lookup?.data?.[0]?.id;
+          if (!id) return { links: [] };
+          const details = await doFetch(`${API}/sessions/${id}`, { headers: { authorization: basic(credential) } })
+            .then((reply) => reply.json()).catch(() => null) as { video?: { path?: string } } | null;
+          return {
+            links: [{ label: "Kobiton session", url: `https://portal.kobiton.com/sessions/${id}` }],
+            ...(details?.video?.path ? { videoUrl: details.video.path } : {}),
+          };
+        },
+      };
+    },
+  };
+}

package/src/runtime/device-clouds/targets.ts

@@ -0,0 +1,44 @@
+// Validating a device-cloud run target. Kept free of Playwright so the
+// registry Worker can use it too.
+import { DEVICE_PROVIDERS, type CloudDevice } from "./types.js";
+
+/** Validates a device-cloud target from a run request. */
+export function parseCloudDevice(raw: Record<string, unknown>): CloudDevice {
+  // "valkyrie" is this provider's pre-rename name, still sent by 0.3.x CLIs.
+  const provider = raw.provider === "valkyrie" ? "bugmole" : raw.provider;
+  if (typeof provider !== "string" || !(DEVICE_PROVIDERS as readonly string[]).includes(provider)) {
+    throw new Error(`Unknown device cloud "${String(provider)}"`);
+  }
+  const platform = raw.platform;
+  if (platform !== "android" && platform !== "ios") throw new Error("A device target needs platform android or ios");
+  const text = (value: unknown, max = 120) => (typeof value === "string" && value.trim() && value.length <= max ? value.trim() : undefined);
+  const deviceName = text(raw.deviceName);
+  if (!deviceName) throw new Error("A device target needs a deviceName");
+  const browserName = raw.browserName === undefined || raw.browserName === null ? undefined : raw.browserName;
+  if (browserName !== undefined && browserName !== "chrome" && browserName !== "safari") throw new Error("browserName must be chrome or safari");
+  const credentialId = text(raw.credentialId, 80);
+  if (provider !== "bugmole" && !credentialId) throw new Error("A device target needs the device-cloud connection to use");
+  const appBuildId = text(raw.appBuildId, 80);
+  if (!browserName && !appBuildId) throw new Error("A device target runs either a browser (browserName) or an uploaded app (appBuildId)");
+  const deviceArn = text(raw.deviceArn, 300);
+  if (deviceArn && !/^arn:aws:devicefarm:[a-z0-9-]+::device:[A-Za-z0-9]+$/.test(deviceArn)) throw new Error("deviceArn isn't a Device Farm device");
+  return {
+    provider: provider as CloudDevice["provider"],
+    ...(credentialId && provider !== "bugmole" ? { credentialId } : {}),
+    platform,
+    deviceName,
+    ...(text(raw.osVersion, 40) ? { osVersion: text(raw.osVersion, 40) } : {}),
+    ...(deviceArn ? { deviceArn } : {}),
+    real: raw.real !== false,
+    ...(browserName ? { browserName } : {}),
+    ...(appBuildId ? { appBuildId } : {}),
+  };
+}
+
+export function cloudTargetId(device: CloudDevice): string {
+  return ["device", device.provider, device.deviceName, device.osVersion ?? "", device.browserName ?? "app"]
+    .map((part) => part.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""))
+    .filter(Boolean)
+    .join("-")
+    .slice(0, 60);
+}

package/src/runtime/device-clouds/types.ts

@@ -0,0 +1,62 @@
+// What a device cloud gives a run: a WebDriver endpoint and capabilities for
+// one real device (or emulator), and what it reports when the session ends.
+
+export type DeviceProvider = "browserstack" | "kobiton" | "aws_device_farm" | "bugmole";
+export const DEVICE_PROVIDERS: readonly DeviceProvider[] = ["browserstack", "kobiton", "aws_device_farm", "bugmole"];
+
+/** A device a run targets on a cloud. */
+export type CloudDevice = {
+  provider: DeviceProvider;
+  /** The workspace's saved credential; absent for Bugmole's own device cloud. */
+  credentialId?: string;
+  platform: "android" | "ios";
+  deviceName: string;
+  osVersion?: string;
+  /** Device Farm's device ARN, when the target came from its catalog. */
+  deviceArn?: string;
+  /** Real hardware, as opposed to an emulator or simulator. */
+  real: boolean;
+  /** Set for mobile web: the flow runs in this browser on the device. */
+  browserName?: "chrome" | "safari";
+  /** Set for a native app: the uploaded build to install. */
+  appBuildId?: string;
+};
+
+export type DeviceCredential = {
+  provider: Exclude<DeviceProvider, "bugmole">;
+  /** BrowserStack user name, Kobiton user name, or AWS access key id. */
+  username: string;
+  /** BrowserStack access key, Kobiton API key, or AWS secret access key. */
+  secret: string;
+  /** AWS Device Farm project ARN. */
+  projectArn?: string;
+};
+
+export type AppBuild = { id: string; platform: "android" | "ios"; filename: string; sha256: string; load: () => Promise<Uint8Array> };
+
+export type SessionReport = {
+  /** Where a person can watch the session back. */
+  links: Array<{ label: string; url: string }>;
+  /** A video file to keep with the run's evidence. */
+  videoUrl?: string;
+  /** Minutes the provider counted (Bugmole's own device cloud bills these). */
+  meteredMinutes?: number;
+};
+
+export type OpenedDeviceSession = {
+  hubUrl: string;
+  capabilities: Record<string, unknown>;
+  authorization?: string;
+  /** Reports the outcome to the provider and collects its recordings. */
+  finish: (outcome: { passed: boolean; webdriverSessionId: string | null; reason?: string }) => Promise<SessionReport>;
+};
+
+export interface DeviceSessionHost {
+  open(input: { device: CloudDevice; name: string; app?: AppBuild }): Promise<OpenedDeviceSession>;
+}
+
+export function cloudDeviceLabel(device: Pick<CloudDevice, "deviceName" | "osVersion" | "browserName" | "real">): string {
+  const os = device.osVersion ? ` (${device.osVersion})` : "";
+  const browser = device.browserName ? ` · ${device.browserName === "chrome" ? "Chrome" : "Safari"}` : "";
+  return `${device.deviceName}${os}${browser}${device.real ? "" : " · emulator"}`;
+}

package/src/runtime/diff-proposal.ts

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import path from "node:path";
+
+interface DiffProposalOptions {
+  filePath: string;
+  evidence: any;
+  failures?: any[];
+}
+
+interface DiffProposalResult {
+  status: "success" | "error";
+  changeSummary?: string;
+  diff?: string;
+  riskLevel?: "low" | "medium" | "high";
+  changeType?: "auto-recoverable" | "auto-learnable" | "plan-breaking";
+  message?: string;
+  error?: string;
+}
+
+/**
+ * Diff Proposal: Analyzes evidence and proposes minimal spec changes
+ */
+export async function proposeDiff(
+  cfg: any,
+  options: DiffProposalOptions,
+): Promise<DiffProposalResult> {
+  try {
+    const { filePath, evidence, failures = [] } = options;
+    const specDir = cfg.runtime.spec_dir || "./spec";
+    const fullPath = path.join(specDir, filePath);
+
+    if (!fs.existsSync(fullPath)) {
+      return {
+        status: "error",
+        error: `File not found: ${filePath}`,
+      };
+    }
+
+    const currentContent = fs.readFileSync(fullPath, "utf-8");
+
+    // TODO: Implement actual diff proposal logic using LLM
+    // This would:
+    // 1. Load the diff-proposal-template.md
+    // 2. Format evidence and failures
+    // 3. Call LLM with template + context
+    // 4. Parse LLM response for CHANGE_SUMMARY, DIFF, EVIDENCE sections
+    // 5. Validate diff against schema
+
+    // For now, generate a structured response
+    const changeSummary = `Proposed changes to ${filePath} based on ${failures.length} failure(s) and execution evidence.`;
+    const diff = `# Proposed diff for ${filePath}\n\n[Diff would be generated by LLM based on evidence]\n\nEvidence: ${JSON.stringify(evidence, null, 2)}\nFailures: ${JSON.stringify(failures, null, 2)}`;
+
+    // Analyze evidence to determine change type and risk
+    let changeType: "auto-recoverable" | "auto-learnable" | "plan-breaking" = "auto-learnable";
+    let riskLevel: "low" | "medium" | "high" = "medium";
+
+    if (failures.length === 0) {
+      changeType = "auto-recoverable";
+      riskLevel = "low";
+    } else if (failures.some((f: any) => f.type === "invariant_violation")) {
+      changeType = "plan-breaking";
+      riskLevel = "high";
+    } else if (
+      failures.some((f: any) => f.type === "selector_mismatch" || f.type === "text_mismatch")
+    ) {
+      changeType = "auto-learnable";
+      riskLevel = "low";
+    }
+
+    return {
+      status: "success",
+      changeSummary,
+      diff,
+      riskLevel,
+      changeType,
+      message: `Diff proposal generated. Change type: ${changeType}, Risk: ${riskLevel}`,
+    };
+  } catch (error: any) {
+    return {
+      status: "error",
+      error: error.message || "Diff proposal failed",
+    };
+  }
+}

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

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { discoveryPersona, discoveryUrl, discoveryUsesAi, withPersonaMarker } from "./discovery-task.js";
+
+test("discoveryUsesAi and discoveryUrl read the title and description a task was queued with", () => {
+  assert.equal(discoveryUsesAi({ title: "Explore with AI shop.test" }), true);
+  assert.equal(discoveryUsesAi({ title: "Explore shop.test" }), false);
+  assert.equal(discoveryUrl({ description: "Explore https://shop.test like a first-time visitor." }), "https://shop.test/");
+  assert.equal(discoveryUrl({ description: "no url here" }), null);
+});
+
+test("a persona round-trips through the description without disturbing the URL extractor", () => {
+  const persona = { name: "Curious", description: "Click into anything unfamiliar." };
+  const description = withPersonaMarker("Explore https://shop.test like a first-time visitor.", persona);
+  assert.deepEqual(discoveryPersona({ description }), persona);
+  assert.equal(discoveryUrl({ description }), "https://shop.test/");
+});
+
+test("a persona description containing markup-like text still round-trips safely", () => {
+  const persona = { name: "Skeptic", description: "Doubt every claim <script>alert(1)</script> and --> weird markers." };
+  const description = withPersonaMarker("Explore https://shop.test.", persona);
+  assert.deepEqual(discoveryPersona({ description }), persona);
+});
+
+test("no persona marker, or one that doesn't decode to a persona, means no persona rather than a thrown error", () => {
+  assert.equal(discoveryPersona({ description: "Explore https://shop.test like a first-time visitor." }), null);
+  const garbage = Buffer.from("not json", "utf8").toString("base64");
+  assert.equal(discoveryPersona({ description: `<!-- persona:${garbage} -->` }), null);
+});