@bugmole/cli 0.5.0 → 0.6.0

package/src/runtime/discovery-task.ts

@@ -6,9 +6,10 @@ import { createProjectObjectStore } from "../storage/create-object-store.js";
 import { projectPrefix } from "../storage/keys.js";
 import { readJourneyGraph, writeJourneyGraph } from "./journey-editor.js";
 import type { JourneyEdge, JourneyNode, UserJourney } from "./journey-graph.js";
-import { discoverSite, stoppedAtSignIn, type DiscoveryResult } from "./site-discovery.js";
+import { discoverSite, stoppedAtSignIn, type DiscoveryLimits, type DiscoveryResult } from "./site-discovery.js";
 import { explorationPrompt, parseCheckedExploration, type ExplorationPersona } from "./ai-exploration.js";
 import { modelCaller } from "./platform-ai.js";
+import { proposeRoleSuggestions } from "./project-roles.js";
 
 /** Discovery tasks queued as "Explore with AI …" also have a model write multi-page journeys. */
 export function discoveryUsesAi(task: Pick<RegistryTask, "title">): boolean {
@@ -69,6 +70,8 @@ export type DiscoveryProgress = {
   events: DiscoveryResult["events"];
   pages: Array<{ route: string; title: string; heading?: string; forms: number }>;
   flows: Array<{ id: string; name: string; kind: "page" | "form" | "journey"; route: string; steps: string[]; planId?: string }>;
+  /** Present once the crawl has finished: the bounds it ran with and what they left out. */
+  limits?: Omit<DiscoveryLimits, "notFollowed"> & { notFollowed: number; notFollowedRoutes: string[] };
 };
 
 export function progressOf(url: string, result: DiscoveryResult, planIds: Record<string, string> = {}): DiscoveryProgress {
@@ -79,6 +82,18 @@ export function progressOf(url: string, result: DiscoveryResult, planIds: Record
     events: result.events.slice(-40),
     pages: result.pages.map((page) => ({ route: page.route, title: page.title, ...(page.heading ? { heading: page.heading } : {}), forms: page.forms.length })),
     flows: result.flows.map((flow) => ({ id: flow.id, name: flow.name, kind: flow.kind, route: flow.route, steps: flow.steps, ...(planIds[flow.id] ? { planId: planIds[flow.id] } : {}) })),
+    ...(result.limits
+      ? {
+        limits: {
+          maxPages: result.limits.maxPages,
+          maxDepth: result.limits.maxDepth,
+          stoppedAtPageLimit: result.limits.stoppedAtPageLimit,
+          notFollowed: result.limits.notFollowed.length,
+          // A sample is enough to show which; every update carries it.
+          notFollowedRoutes: result.limits.notFollowed.slice(0, 20),
+        },
+      }
+      : {}),
   };
 }
 
@@ -191,7 +206,7 @@ export async function saveDiscovery(cfg: WorkerConfig, client: Pick<ControlPlane
  */
 export async function runDiscoveryTask(
   cfg: WorkerConfig,
-  client: Pick<ControlPlaneClient, "claimTask" | "updateTask" | "publishPlan">,
+  client: Pick<ControlPlaneClient, "claimTask" | "updateTask" | "publishPlan"> & Partial<Pick<ControlPlaneClient, "proposeRole">>,
   task: RegistryTask,
   workerId: string,
   discover: typeof discoverSite = discoverSite,
@@ -200,6 +215,16 @@ export async function runDiscoveryTask(
     claimed?: boolean;
     /** Called once if the registry answers an update with `stop`. */
     onStop?: (signal: { reason: string; message: string }) => void;
+    /**
+     * Signs in before exploring (a cloud runner with the project's sign-in
+     * flow) and returns the saved browser session to explore in.
+     */
+    signIn?: (url: string) => Promise<string>;
+    /**
+     * How far to explore: the workspace plan's bounds on Bugmole Cloud, the
+     * machine's own settings on a project worker. Discovery's defaults otherwise.
+     */
+    limits?: { maxPages?: number; maxDepth?: number };
   } = {},
 ): Promise<void> {
   const url = discoveryUrl(task);
@@ -242,12 +267,27 @@ export async function runDiscoveryTask(
   heartbeat.unref?.();
   try {
     await send("running");
+    // Sign-in happens before discovery has a result to report into, so its
+    // events are kept here and put in front of discovery's own.
+    const before: DiscoveryResult["events"] = [];
+    let storageState: string | undefined;
+    if (options.signIn) {
+      before.push({ at: new Date().toISOString(), kind: "visit", text: "Signing in with the project's sign-in flow…" });
+      latest = progressOf(url, { baseUrl: url, pages: [], flows: [], events: before });
+      await send("running");
+      storageState = await options.signIn(url);
+      before.push({ at: new Date().toISOString(), kind: "visit", text: "Signed in; exploring as a signed-in user" });
+    }
     const result = await discover(url, {
+      ...(storageState ? { storageState } : {}),
+      ...(options.limits?.maxPages ? { maxPages: options.limits.maxPages } : {}),
+      ...(options.limits?.maxDepth ? { maxDepth: options.limits.maxDepth } : {}),
       onEvent: async (_event, snapshot) => {
-        latest = progressOf(url, snapshot);
+        latest = progressOf(url, { ...snapshot, events: [...before, ...snapshot.events] });
         await send("running");
       },
     });
+    result.events.unshift(...before);
     // Everything reachable was a sign-in screen. Say so plainly, and don't
     // ask AI to imagine the app behind it: that spends credits on journeys
     // through pages nobody has seen.
@@ -256,11 +296,29 @@ export async function runDiscoveryTask(
       result.events.push({
         at: new Date().toISOString(),
         kind: "skip",
-        text: "Stopped at a sign-in page: Bugmole Cloud can't sign in to your app yet, so everything behind it is unexplored. "
-          + "To explore signed in, run discovery from your machine or CI with a sign-in flow: bugmole --mode discover --sign-in <flow>.",
+        text: storageState
+          ? "Stopped at a sign-in page even after the sign-in flow passed, so everything behind it is unexplored. "
+            + "Check that the sign-in flow ends signed in (assert something only a signed-in user sees)."
+          : "Stopped at a sign-in page, so everything behind it is unexplored. To explore signed in, add a sign-in flow and its secrets "
+            + "under Settings → Sign-in for cloud runs, or run discovery from your machine or CI: bugmole --mode discover --sign-in <flow>.",
       });
       latest = progressOf(url, result);
       await send("running");
+      // A sign-in wall says the app has signed-out and signed-in people:
+      // suggest both roles for a person to confirm on the Roles page.
+      if (client.proposeRole && !storageState) {
+        const evidence = `Exploring ${url} reached only a sign-in page`;
+        const proposed = await proposeRoleSuggestions([
+          { name: "guest", description: "Visitor who is not signed in and only sees public screens.", source: "sign_in_wall", evidence },
+          { name: "member", description: "Signed-in user who gets past the sign-in wall.", source: "sign_in_wall", evidence },
+        ], { proposeRole: client.proposeRole.bind(client) }).catch(() => []);
+        const sent = proposed.filter((role) => role.status === "suggested" && !role.alreadyDecided).map((role) => role.name);
+        if (sent.length) {
+          result.events.push({ at: new Date().toISOString(), kind: "flows", text: `Suggested the roles ${sent.join(" and ")} for you to confirm under Settings → Roles` });
+          latest = progressOf(url, result);
+          await send("running");
+        }
+      }
     }
     if (discoveryUsesAi(task) && !signInWall) {
       const caller = modelCaller(cfg, { projectId: cfg.project?.id ?? "default", requestId: task.id });
@@ -292,7 +350,10 @@ export async function runDiscoveryTask(
     latest = progressOf(url, result, planIds);
     await send("completed", {
       completionSummary: `Explored ${result.pages.length} page(s) of ${url} and discovered ${result.flows.length} flow(s).`
-        + (signInWall ? " Stopped at a sign-in page; the app behind it is unexplored." : ""),
+        + (signInWall ? " Stopped at a sign-in page; the app behind it is unexplored." : "")
+        + (result.limits?.notFollowed.length
+          ? ` ${result.limits.notFollowed.length} linked page(s) were not opened (limit: ${result.limits.maxPages} pages, ${result.limits.maxDepth} clicks deep).`
+          : ""),
     });
   } catch (error) {
     await send("error", { errorMessage: error instanceof Error ? error.message : String(error) });

package/src/runtime/executor.ts

@@ -11,6 +11,8 @@ import { journeyScreenshotKey } from "./journey-evidence.js";
 import type { AppDriver, DriverPlatform } from "./driver.js";
 import { MaestroDriver } from "./maestro-driver.js";
 import { PlaywrightDriver } from "./playwright-driver.js";
+import { withFlowSecrets } from "./secret-driver.js";
+import { secretMap } from "./secret-sources.js";
 import { recoverDriverFailure } from "./driver-recovery.js";
 import { startAndroidScreenRecording } from "./android-screen-record.js";
 import { startIosScreenRecording } from "./ios-screen-record.js";
@@ -115,16 +117,27 @@ export interface ExecutionResult {
 }
 
 function configuredDriver(cfg: any, driverId: string): AppDriver {
+  // Flows type {{secret.NAME}} from wherever the project keeps it (its
+  // config's secrets: map, or this machine's keychain).
+  const secrets = (driver: AppDriver) => {
+    const { map } = secretMap(cfg);
+    return withFlowSecrets(driver, {
+      map,
+      projectId: cfg.project?.id ?? "default",
+      // A cloud runner has the project's released secrets already; it has no keychain.
+      localFallback: !process.env.BUGMOLE_RUN_TOKEN,
+    });
+  };
   if (driverId === "maestro") {
-    return new MaestroDriver({
+    return secrets(new MaestroDriver({
       command: cfg.execution?.maestro?.command,
       extraArgs: Array.isArray(cfg.execution?.maestro?.args) ? cfg.execution.maestro.args : undefined,
-    });
+    }));
   }
   if (driverId === "playwright") {
-    return new PlaywrightDriver({
+    return secrets(new PlaywrightDriver({
       headless: cfg.execution?.playwright?.headless,
-    });
+    }));
   }
   throw new Error(`No app driver adapter is registered for "${driverId}"`);
 }
@@ -400,12 +413,7 @@ export async function execute(cfg: any, runOptions: RunOptions): Promise<Executi
         stepsPassed: 0,
         stepsFailed: 0,
         error:
-          `Plan not found: ${planPath}\n` +
-          `Plan ID provided: ${planId}\n` +
-          `Spec dir: ${specDir}\n` +
-          `Plans dir: ${plansDir}\n` +
-          `Current working directory: ${process.cwd()}\n` +
-          `Environment variables: CURSOR_PROJECT_DIRECTORY=${process.env.CURSOR_PROJECT_DIRECTORY || "not set"}, BUGMOLE_PROJECT_DIR=${process.env.BUGMOLE_PROJECT_DIR || "not set"}`,
+          `No plan "${planId}" at ${planPath}. Create it with bugmole_plan (or bugmole --mode plan), or check the plan ID and that Bugmole runs in your project folder (now ${process.cwd()}).`,
       };
     }
 

package/src/runtime/explorer.test.ts

@@ -99,3 +99,35 @@ test("manage hub links resolve against optional catch-all resource routes", asyn
     assert.ok(targets.has(route), `expected /manage to link to ${route}`);
   }
 });
+
+test("an app with no route files is explored by crawling it, and recorded transitions survive re-exploring", async () => {
+  const projectDir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-explorer-plain-"));
+  await fs.writeFile(path.join(projectDir, "server.mjs"), "// a plain http server\n");
+  const specDir = path.join(projectDir, "spec");
+  const cfg = {
+    runtime: { spec_dir: specDir, artifacts_dir: path.join(projectDir, "runs") },
+    cursor_driver: { project_directory: projectDir },
+    project: { id: "plain" },
+  };
+  const page = (route: string, title: string, links: Array<{ label: string; route: string }>) => ({ route, url: `http://127.0.0.1:1${route}`, title, links });
+  const discover = async () => ({
+    pages: [
+      page("/", "Home", [{ label: "Pricing", route: "/pricing" }, { label: "Sign up", route: "/signup" }]),
+      page("/pricing", "Pricing", [{ label: "Home", route: "/" }]),
+      page("/signup", "Sign up", []),
+    ],
+  });
+  const first = await explore(cfg, { baseUrl: "http://127.0.0.1:1", captureScreenshots: false, discover });
+  assert.equal(first.status, "success");
+  let graph = JSON.parse(await fs.readFile(path.join(specDir, "journeys.graph.json"), "utf-8"));
+  assert.deepEqual(graph.nodes.map((node: { route: string }) => node.route).sort(), ["/", "/pricing", "/signup"]);
+  assert.ok(graph.edges.some((edge: { from: string; to: string; label?: string }) => edge.from === "screen:/" && edge.to === "screen:/signup" && edge.label === "Sign up"));
+
+  // A transition an agent recorded by hand, for its own journey.
+  graph.edges.push({ id: "screen:/signup->screen:/:manual", from: "screen:/signup", to: "screen:/", label: "Back home" });
+  graph.journeys.push({ id: "manual", name: "Manual", actor: "visitor", nodeIds: ["screen:/signup", "screen:/"], edgeIds: ["screen:/signup->screen:/:manual"], revision: 1, status: "draft", startNodeId: "screen:/signup" });
+  await fs.writeFile(path.join(specDir, "journeys.graph.json"), JSON.stringify(graph));
+  await explore(cfg, { baseUrl: "http://127.0.0.1:1", captureScreenshots: false, discover });
+  graph = JSON.parse(await fs.readFile(path.join(specDir, "journeys.graph.json"), "utf-8"));
+  assert.ok(graph.edges.some((edge: { id: string }) => edge.id === "screen:/signup->screen:/:manual"));
+});

package/src/runtime/explorer.ts

@@ -21,6 +21,10 @@ interface ExploreOptions {
   accessMethod?: "configured" | "handoff" | "manual" | "unknown";
   journeyId?: string;
   actor?: string;
+  /** false: never crawl the running app when the source has no route files. */
+  crawl?: boolean;
+  /** The crawler, replaceable in tests. */
+  discover?: (baseUrl: string, options: { maxPages?: number; maxDepth?: number }) => Promise<{ pages: Array<{ route: string; url: string; title: string; heading?: string; links: Array<{ label: string; route: string }> }> }>;
 }
 
 interface ExploreResult {
@@ -572,10 +576,43 @@ export async function explore(cfg: any, options: ExploreOptions): Promise<Explor
         sourcePaths: entry.source ? [entry.source] : [],
       });
     }
+    // No route files (Express, Fastify, a plain http server, a framework the
+    // walk doesn't know): learn the screens from the running app instead,
+    // by clicking through it the way site discovery does.
+    const crawledEdges: any[] = [];
+    if (discoveredNodes.size === 0 && options.crawl !== false) {
+      const { discoverSite } = await import("./site-discovery.js");
+      const site = await (options.discover ?? discoverSite)(baseUrl, { maxPages: 30, maxDepth: 3 });
+      for (const page of site.pages) {
+        const route = normalizeRoute(page.route) || "/";
+        const nodeId = `screen:${route}`;
+        if (discoveredNodes.has(nodeId)) continue;
+        discoveredNodes.set(nodeId, {
+          id: nodeId,
+          title: page.heading || page.title || semanticScreenTitle(route),
+          kind: "screen",
+          signature: `${projectRoot}@route:${route}`,
+          route,
+          source: "running app",
+          sourcePaths: [],
+          runtimeProbe: { status: "reachable", url: page.url },
+          metadata: { discoveredBy: "site-discovery" },
+        });
+      }
+      for (const page of site.pages) {
+        const from = `screen:${normalizeRoute(page.route) || "/"}`;
+        for (const [index, link] of page.links.entries()) {
+          const to = `screen:${normalizeRoute(link.route) || "/"}`;
+          if (to === from || !discoveredNodes.has(to)) continue;
+          crawledEdges.push({ id: `${from}->${to}:crawl-${index}`, from, to, label: link.label, action: `navigate:${normalizeRoute(link.route) || "/"}`, source: "running app" });
+        }
+      }
+    }
     graph.nodes = [...discoveredNodes.values()];
     // Resolve links after all route files are known so source order cannot
     // make a valid link look unresolved.
     const routeNodes = graph.nodes as any[];
+    const previousEdges: any[] = Array.isArray(graph.edges) ? graph.edges : [];
     graph.edges = [];
     for (const filePath of sourceFiles) {
       const relativePath = path.relative(projectRoot, filePath);
@@ -619,6 +656,17 @@ export async function explore(cfg: any, options: ExploreOptions): Promise<Explor
         });
       }
     }
+    for (const edge of crawledEdges) {
+      if (!graph.edges.some((existing: any) => existing.from === edge.from && existing.to === edge.to)) graph.edges.push(edge);
+    }
+    // Transitions a person or an agent recorded for a journey aren't in the
+    // source or the crawl: keep them while both of their screens still exist,
+    // or rebuilding the sitemap breaks those journeys.
+    const recorded = new Set(existingJourneys.flatMap((journey: any) => Array.isArray(journey.edgeIds) ? journey.edgeIds : []));
+    for (const edge of previousEdges) {
+      if (!recorded.has(edge?.id) || graph.edges.some((existing: any) => existing.id === edge.id)) continue;
+      if (discoveredNodes.has(edge.from) && discoveredNodes.has(edge.to)) graph.edges.push(edge);
+    }
     for (const [index, link] of (routesManifest.links ?? []).entries()) {
       if (!link?.from || !link?.to) continue;
       const fromNode = routeNodes.find((candidate: any) =>

package/src/runtime/flow-language.ts

@@ -1,4 +1,5 @@
 import YAML from "yaml";
+import { registerSecretValue } from "./secret-redaction.js";
 
 /**
  * The Maestro-style flow subset this project's web plans author.
@@ -310,6 +311,13 @@ export type InterpolateOptions = {
   env?: Readonly<Record<string, string | undefined>>;
 };
 
+/** The secret names a flow's text references as `{{secret.NAME}}`, sorted and unique. */
+export function referencedSecretNames(content: string): string[] {
+  const names = new Set<string>();
+  for (const match of content.matchAll(/\{\{\s*secret\.([a-zA-Z0-9_]+)\s*\}\}/g)) names.add(match[1]);
+  return [...names].sort();
+}
+
 /**
  * Substitutes `{{name}}` tokens with a value bound earlier in the same flow
  * (currently, only requestTempEmail binds one). Plain text with no template
@@ -335,6 +343,8 @@ export function interpolateTemplate(
       if (value === undefined || value === "") {
         throw new Error(`Flow references "{{secret.${name}}}", but ${variable} is not set on this worker.`);
       }
+      // Typed from here on, so it must never show up in a log or result.
+      registerSecretValue(value);
       return value;
     }
     if (!(name in context)) {
@@ -403,22 +413,26 @@ export function describeAddressForLog(address: string): string {
  * have templated. `retry`'s nested steps are deliberately left alone here --
  * the driver interpolates each one individually as it actually executes it.
  */
-export function interpolateStep(step: FlowStep, context: Readonly<Record<string, string>>): FlowStep {
+export function interpolateStep(
+  step: FlowStep,
+  context: Readonly<Record<string, string>>,
+  options: Pick<InterpolateOptions, "env"> = {},
+): FlowStep {
   switch (step.type) {
     case "tapOn":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "inputText":
-      return { ...step, text: interpolateTemplate(step.text, context, { allowSecrets: true }) };
+      return { ...step, text: interpolateTemplate(step.text, context, { ...options, allowSecrets: true }) };
     case "assertVisible":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "assertNotVisible":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "assertClickable":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "scrollUntilVisible":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "openLink":
-      return { ...step, url: interpolateTemplate(step.url, context) };
+      return { ...step, url: interpolateTemplate(step.url, context, options) };
     default:
       return step;
   }

package/src/runtime/init-wizard.ts

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import YAML from "yaml";
+import { describeDetection, detectProjectIdentity, type ProjectIdentityDetection } from "./project-identity.js";
 
 export type StorageProvider = "local" | "gcs" | "s3" | "r2" | "bugmole";
 
@@ -30,6 +31,10 @@ export type InitOptions = {
   endpoint?: string;
   cloudProjectId?: string;
   accountId?: string;
+  /** The app's folder inside the repository, for a repository with several apps. */
+  appPath?: string;
+  /** The app's URL (a public one identifies the project by domain when there is no git remote). */
+  appUrl?: string;
 };
 
 export type InitConfig = {
@@ -50,8 +55,40 @@ export type InitConfig = {
   endpoint?: string;
   cloudProjectId?: string;
   accountId?: string;
+  /** Which app of the repository this project is ("." for the root). */
+  appPath?: string;
 };
 
+/**
+ * The registry refused a project or workspace because of the plan (402
+ * plan_limit or free_workspace_exists). Carries the registry's own message
+ * and the Billing link, so the CLI prints those instead of a stack trace.
+ */
+export class PlanLimitError extends Error {
+  constructor(message: string, readonly billingUrl: string, readonly code: string) {
+    super(message);
+    this.name = "PlanLimitError";
+  }
+}
+
+/** A PlanLimitError for a registry refusal about the plan; null for anything else. */
+export function planLimitFromRegistry(
+  status: number,
+  body: { error?: string; code?: string; upgradeUrl?: string; billingUrl?: string } | null,
+  dashboardUrl: string,
+): PlanLimitError | null {
+  if (!body || (body.code !== "plan_limit" && body.code !== "free_workspace_exists" && body.code !== "identity_in_use" && status !== 402)) return null;
+  const base = dashboardUrl.replace(/\/$/, "");
+  const relative = typeof body.upgradeUrl === "string" && body.upgradeUrl.startsWith("/billing") ? body.upgradeUrl : "/billing";
+  const billingUrl = typeof body.billingUrl === "string" && /^https?:\/\//.test(body.billingUrl) ? body.billingUrl : `${base}${relative}`;
+  return new PlanLimitError(body.error || "Your Bugmole plan doesn't allow this.", billingUrl, body.code ?? "plan_limit");
+}
+
+/** What `bugmole init` prints for a plan refusal. */
+export function describePlanLimit(error: PlanLimitError): string {
+  return `${error.message}\nSee plans and upgrade: ${error.billingUrl}`;
+}
+
 const providers = new Set<StorageProvider>(["local", "gcs", "s3", "r2", "bugmole"]);
 
 export function validateStorageProvider(value: string): StorageProvider {
@@ -90,6 +127,7 @@ function existingDefaults(cwd: string, configPath: string): Partial<InitConfig>
     endpoint: storage[provider]?.endpoint,
     cloudProjectId: storage[provider]?.project_id,
     accountId: storage[provider]?.account_id,
+    appPath: project.app_path ?? project.appPath,
   };
 }
 
@@ -134,7 +172,7 @@ project:
   workspace_id: ${config.workspaceId}
   workspace_name: ${JSON.stringify(config.workspaceName)}
   environment: ${config.environment}
-  spec_dir: ${config.specDir}
+${config.appPath ? `  app_path: ${JSON.stringify(config.appPath)}\n` : ""}  spec_dir: ${config.specDir}
   evidence_manifest: ${config.evidenceManifest}
   evidence_screenshots: ${config.evidenceScreenshots}
 
@@ -167,7 +205,8 @@ function renderEnv(config: InitConfig): string {
     `BUGMOLE_ENVIRONMENT=${config.environment}`,
     `BUGMOLE_STORAGE_PROVIDER=${config.storageProvider}`,
     `BUGMOLE_LOCAL_ARTIFACTS_DIR=${config.artifactsDir}`,
-    `BUGMOLE_AEGIS_EMAIL=${JSON.stringify(process.env.BUGMOLE_AEGIS_EMAIL?.trim() ?? "")}`,
+    // The email you sign in with, remembered to prefill the next sign-in.
+    ...(process.env.BUGMOLE_AEGIS_EMAIL?.trim() ? [`BUGMOLE_AEGIS_EMAIL=${JSON.stringify(process.env.BUGMOLE_AEGIS_EMAIL.trim())}`] : []),
     "",
   ];
   if (config.storageProvider === "gcs") {
@@ -199,11 +238,50 @@ function renderEnv(config: InitConfig): string {
   return `${lines.join("\n")}\n`;
 }
 
+/** The registry matched this app to a project that already exists (a teammate's): use its id from now on. */
+function adoptProjectId(configFile: string, envFile: string, config: InitConfig, projectId: string): void {
+  if (projectId === config.projectId) return;
+  if (fs.existsSync(configFile)) {
+    const text = fs.readFileSync(configFile, "utf8");
+    fs.writeFileSync(configFile, text.replace(/^(project:\r?\n  id: ).*$/m, `$1${projectId}`), "utf8");
+  }
+  if (fs.existsSync(envFile)) writeEnvValue(envFile, "BUGMOLE_PROJECT_ID", projectId);
+  config.projectId = projectId;
+}
+
+/** Which app this is; never fails init (detection is best-effort). */
+function detectIdentity(cwd: string, options: InitOptions, defaults: Partial<InitConfig>): ProjectIdentityDetection | null {
+  try {
+    return detectProjectIdentity({
+      cwd,
+      appPath: options.appPath ?? defaults.appPath,
+      appUrl: options.appUrl ?? (process.env.BUGMOLE_BASE_URL?.trim() || process.env.PLAYWRIGHT_BASE_URL?.trim() || undefined),
+    });
+  } catch {
+    return null;
+  }
+}
+
 async function ask(rl: readline.Interface, label: string, fallback: string): Promise<string> {
   const answer = await rl.question(`${label} [${fallback}]: `);
   return valueOr(answer, fallback);
 }
 
+/**
+ * Adds the env file to the repository's .gitignore (when the workspace is a
+ * git repository and doesn't ignore it yet). Returns whether it added it.
+ */
+export function ensureGitignored(cwd: string, file: string): boolean {
+  if (!fs.existsSync(path.join(cwd, ".git"))) return false;
+  const gitignore = path.join(cwd, ".gitignore");
+  const entry = `/${file.replace(/^\.\//, "")}`;
+  const current = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, "utf8") : "";
+  const lines = current.split(/\r?\n/).map((line) => line.trim());
+  if (lines.includes(entry) || lines.includes(entry.slice(1)) || lines.includes(".bugmole.env*") || lines.includes("*.env")) return false;
+  fs.writeFileSync(gitignore, `${current}${current && !current.endsWith("\n") ? "\n" : ""}${entry}\n`, "utf8");
+  return true;
+}
+
 export async function runInitWizard(
   options: InitOptions = {},
 ): Promise<{ configPath: string; envPath: string; config: InitConfig }> {
@@ -232,6 +310,12 @@ export async function runInitWizard(
         await choose(options.storageProvider, "Storage provider (local|gcs|s3|r2|bugmole)", valueOr(defaults.storageProvider, "local")),
       ),
     };
+    const detection = detectIdentity(cwd, options, defaults);
+    if (detection) {
+      for (const line of describeDetection(detection)) console.log(line);
+      if (detection.app && detection.app.path !== ".") config.appPath = detection.app.path;
+    }
+    const identity = detection?.identity ?? undefined;
     if (config.storageProvider !== "local" && config.storageProvider !== "bugmole") {
       config.bucket = await choose(options.bucket, "Bucket", valueOr(defaults.bucket, ""));
       if (config.storageProvider === "gcs")
@@ -256,6 +340,7 @@ export async function runInitWizard(
       if (options.force || !fs.existsSync(envFile)) {
         fs.writeFileSync(envFile, renderEnv(config), "utf8");
         console.log(`Generated ${configPath} and ${envPath}.`);
+        if (ensureGitignored(cwd, envPath)) console.log(`Added ${envPath} to .gitignore: it will hold your API key.`);
       } else {
         console.log(`Generated ${configPath}; kept existing ${envPath}.`);
       }
@@ -264,6 +349,8 @@ export async function runInitWizard(
     }
     const registryUrl =
       process.env.BUGMOLE_REGISTRY_URL?.trim() || "https://api.bugmole.com";
+    const dashboardUrl =
+      process.env.BUGMOLE_DASHBOARD_URL?.trim() || "https://app.bugmole.com";
     const apiKey = process.env.BUGMOLE_API_KEY?.trim();
     if (registryUrl && apiKey && shouldWrite) {
       const headers: Record<string, string> = {
@@ -282,12 +369,22 @@ export async function runInitWizard(
           workspaceName: config.workspaceName,
           environment: config.environment,
           storageProvider: config.storageProvider,
+          identity,
         }),
       });
       if (!response.ok) {
-        throw new Error(`Bugmole registry rejected project registration (${response.status})`);
+        const refusal = await response.json().catch(() => null) as { error?: string; code?: string; upgradeUrl?: string; billingUrl?: string } | null;
+        const planLimit = planLimitFromRegistry(response.status, refusal, dashboardUrl);
+        if (planLimit) throw planLimit;
+        throw new Error(`Bugmole registry rejected project registration (${response.status})${refusal?.error ? `: ${refusal.error}` : ""}`);
+      }
+      const registered = await response.json().catch(() => null) as { project?: { id?: string }; existing?: boolean } | null;
+      if (registered?.existing && registered.project?.id) {
+        adoptProjectId(configFile, envFile, config, registered.project.id);
+        console.log(`This app is already project ${config.projectId} in the workspace; joined it instead of creating another.`);
+      } else {
+        console.log(`Registered ${config.projectId} with the Bugmole registry.`);
       }
-      console.log(`Registered ${config.projectId} with the Bugmole registry.`);
     } else if (registryUrl && !apiKey && shouldWrite && !nonInteractive) {
       const createResponse = await fetch(`${registryUrl.replace(/\/$/, "")}/api/device-authorizations`, {
         method: "POST",
@@ -297,6 +394,7 @@ export async function runInitWizard(
           projectName: config.projectName,
           environment: config.environment,
           storageProvider: config.storageProvider,
+          identity,
         }),
       });
       const attempt = await createResponse.json().catch(() => null) as {
@@ -309,8 +407,6 @@ export async function runInitWizard(
       if (!createResponse.ok || !attempt?.attemptId || !attempt.code || !attempt.pollSecret) {
         throw new Error(attempt?.error ?? "Unable to start Bugmole device registration");
       }
-      const dashboardUrl =
-        process.env.BUGMOLE_DASHBOARD_URL?.trim() || "https://app.bugmole.com";
       const registrationUrl =
         `${dashboardUrl.replace(/\/$/, "")}/register?attemptId=${encodeURIComponent(attempt.attemptId)}&projectId=${encodeURIComponent(config.projectId)}${process.env.BUGMOLE_AEGIS_EMAIL?.trim() ? `&email=${encodeURIComponent(process.env.BUGMOLE_AEGIS_EMAIL.trim())}` : ""}`;
       console.log(`Open ${registrationUrl} and enter code: ${attempt.code}`);
@@ -327,14 +423,24 @@ export async function runInitWizard(
           status?: string;
           token?: string;
           email?: string;
+          projectId?: string;
           alreadyInitialized?: boolean;
           error?: string;
+          code?: string;
+          upgradeUrl?: string;
+          billingUrl?: string;
         } | null;
         if (result?.status === "pending") continue;
         if (!pollResponse.ok) {
+          const planLimit = planLimitFromRegistry(pollResponse.status, result, dashboardUrl);
+          if (planLimit) throw planLimit;
           const detail = result?.error ?? result?.status ?? `HTTP ${pollResponse.status}`;
           throw new Error(`Bugmole device registration failed: ${detail}`);
         }
+        if (result?.projectId && result.projectId !== config.projectId) {
+          adoptProjectId(configFile, envFile, config, result.projectId);
+          console.log(`This app is already project ${config.projectId}; this machine joined it.`);
+        }
         if (result?.alreadyInitialized) {
           throw new Error("This Aegis account already has an API key; revoke it or use that key in .bugmole.env.");
         }