@bugmole/cli 0.4.0

package/src/runtime/executor.ts

@@ -0,0 +1,921 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { AppiumDriver } from "./appium-driver.js";
+import type { DeviceCloudAccess } from "./device-clouds/index.js";
+import { json, type ObjectStore } from "../storage/object-store.js";
+import { runKey, type RunManifest, projectPrefix, runPrefix } from "../storage/keys.js";
+import type { JourneyScreenshotEvidence } from "./journey-graph.js";
+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 { recoverDriverFailure } from "./driver-recovery.js";
+import { startAndroidScreenRecording } from "./android-screen-record.js";
+import { startIosScreenRecording } from "./ios-screen-record.js";
+import { defaultTargets, targetLabel, type RunTarget } from "./browser-matrix.js";
+import { applyFlowChanges, type FailureAnalysis, type FailureContext, type FlowChange } from "./failure-analysis.js";
+import { describeStepLabel, parseMaestroStyleFlow, type FlowStep } from "./flow-language.js";
+import { explainWith } from "./ai-analysis.js";
+import { parseRepair, repairPrompt } from "./ai-repair.js";
+import { modelCaller, type ModelCallIds } from "./platform-ai.js";
+import {
+  aggregateTargetResults,
+  queuedTargetResult,
+  resolveTargetConcurrency,
+  runPool,
+  stepCounts,
+  type TargetResult,
+} from "./target-runner.js";
+
+export interface RunOptions {
+  planId: string;
+  journeyId?: string;
+  runId?: string;
+  /**
+   * The selected environment's base URL. Overrides the plan target, and moves
+   * absolute flow URLs onto this origin so a flow runs where it was sent.
+   */
+  baseUrl?: string;
+  /** Browsers/devices to fan a web run out across. Defaults to execution.playwright config. */
+  targets?: RunTarget[];
+  onProgress?: (progress: {
+    currentStep: string;
+    stepsExecuted: number;
+    stepsPassed: number;
+    stepsFailed: number;
+    node?: NodeExecutionResult;
+    targetResults?: TargetResult[];
+  }) => void | Promise<void>;
+  captureScreenshot?: (nodeId: string, action: string) => Promise<Uint8Array>;
+  /**
+   * A fix to apply to the flow before running it. "suggested" applies the
+   * earlier run's checked suggestion (the dashboard's "Apply fix"); "ai" asks
+   * a model for the edit first, from the earlier failure (AI test repair).
+   */
+  applyFix?: {
+    changes: FlowChange[];
+    sourceRunId?: string;
+    targetId?: string;
+    mode?: "suggested" | "ai";
+    failureContext?: FailureContext;
+    analysis?: FailureAnalysis;
+  };
+  /** Test seam: builds the driver for a driver id instead of the registered adapters. */
+  driverFactory?: (cfg: any, driverId: string) => AppDriver;
+  /** Credentials and app builds for device-cloud targets, loaded from the registry. */
+  deviceClouds?: DeviceCloudAccess;
+}
+
+export interface NodeExecutionResult {
+  nodeId: string;
+  action: string;
+  status: "success" | "blocked" | "failed";
+  reason: { code: string; message: string; details?: unknown };
+  proofs: any[];
+  startedAt: string;
+  completedAt: string;
+  screenshot?: JourneyScreenshotEvidence;
+}
+
+export interface ExecutionResult {
+  status: "success" | "error" | "partial";
+  runId: string;
+  journeyId: string;
+  stepsExecuted: number;
+  stepsPassed: number;
+  stepsFailed: number;
+  driver?: string;
+  platform?: string;
+  recoveryAttempts?: number;
+  failureCode?: string;
+  evidencePath?: string;
+  /** Object-store key of the run's manifest.json. */
+  manifestKey?: string;
+  message?: string;
+  error?: string;
+  /** Per browser/device outcome when the run fanned out across a matrix. */
+  targetResults?: TargetResult[];
+  durationMs?: number;
+  /** Set when a suggested fix was written to the flow before this run. */
+  fixApplied?: { sourceRunId?: string; targetId?: string; flow: string };
+  results?: Array<{
+    step: string;
+    nodeId: string;
+    action: string;
+    outcome: "PASS" | "FAIL" | "UNKNOWN";
+    proofs: any[];
+    status: NodeExecutionResult["status"];
+    reason: NodeExecutionResult["reason"];
+    startedAt: string;
+    completedAt: string;
+    screenshot?: JourneyScreenshotEvidence;
+  }>;
+}
+
+function configuredDriver(cfg: any, driverId: string): AppDriver {
+  if (driverId === "maestro") {
+    return 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({
+      headless: cfg.execution?.playwright?.headless,
+    });
+  }
+  throw new Error(`No app driver adapter is registered for "${driverId}"`);
+}
+
+/**
+ * Executor: Executes plan steps with Playwright, produces Proof Tokens
+ */
+/**
+ * A cloud worker starts from a clean container, so the plan may exist only in the object store,
+ * where the planner publishes it (projects/<id>/plans/<planId>.flow.yaml).
+ */
+export async function readStoredPlan(store: ObjectStore, projectId: string, planId: string): Promise<string | undefined> {
+  if (!/^[a-z0-9._-]+$/i.test(planId)) return undefined;
+  const base = planId.replace(/(\.flow)?\.ya?ml$/i, "");
+  for (const name of [`${base}.flow.yaml`, `${base}.yaml`]) {
+    const key = `${projectPrefix(projectId)}/plans/${name}`;
+    try {
+      if (await store.has(key)) return await store.getText(key);
+    } catch {
+      // Try the next candidate; a missing plan is reported by the caller.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolves a plan's flow file, downloading it from the object store (projects/<id>/spec/<flow>)
+ * into the run's artifacts directory when it isn't on the worker's disk.
+ */
+export async function resolveFlowPath(
+  store: ObjectStore,
+  projectId: string,
+  runId: string,
+  artifactsDir: string,
+  flowReference: string,
+  localFlowPath: string,
+): Promise<string> {
+  if (path.isAbsolute(flowReference) || fs.existsSync(localFlowPath)) return localFlowPath;
+  const normalized = flowReference.replaceAll("\\", "/").replace(/^\/+/, "");
+  if (normalized.split("/").includes("..")) return localFlowPath;
+  const key = `${projectPrefix(projectId)}/spec/${normalized}`;
+  try {
+    if (!(await store.has(key))) return localFlowPath;
+    const destination = path.join(artifactsDir, projectId, runId, "spec", normalized);
+    await fs.promises.mkdir(path.dirname(destination), { recursive: true });
+    await fs.promises.writeFile(destination, await store.get(key));
+    return destination;
+  } catch {
+    return localFlowPath;
+  }
+}
+
+/** The plan's step nodes after a fix: inserted flow steps get nodes of their own. */
+function syncPlanSteps(planSteps: any[], changes: readonly FlowChange[], fixedSteps: FlowStep[]): any[] {
+  const next = [...planSteps];
+  const ordered = [...changes].sort((left, right) => right.index - left.index);
+  let added = 0;
+  for (const change of ordered) {
+    if (change.op === "insert") {
+      const nodes = change.steps.map((_step, offset) => {
+        added += 1;
+        return { node_id: `fix-${added}`, action: describeStepLabel(fixedSteps[change.index + offset]) };
+      });
+      next.splice(change.index, 0, ...nodes);
+    } else {
+      next[change.index] = { ...next[change.index], action: describeStepLabel(fixedSteps[change.index]) };
+    }
+  }
+  return next;
+}
+
+/**
+ * Lets the project's AI model explain a failed target in plain words, and
+ * rewrites that target's analysis.json in place before it is uploaded.
+ */
+async function refineAnalysis(cfg: any, result: Awaited<ReturnType<AppDriver["run"]>>, ids: ModelCallIds): Promise<FailureAnalysis | undefined> {
+  const analysisFile = result.artifacts.find((artifact) => artifact.name === "analysis.json");
+  const contextFile = result.artifacts.find((artifact) => artifact.name === "failure-context.json");
+  if (!analysisFile) return undefined;
+  try {
+    const analysis = JSON.parse(await fs.promises.readFile(analysisFile.path, "utf8")) as FailureAnalysis;
+    if (!contextFile) return analysis;
+    const context = JSON.parse(await fs.promises.readFile(contextFile.path, "utf8")) as FailureContext;
+    // The project's own model, else Bugmole AI (1 credit); without either the
+    // rules' explanation stands.
+    const caller = modelCaller(cfg, ids);
+    if (!caller) return analysis;
+    const explained = await explainWith(async (prompt) => caller(prompt, "analysis"), analysis, context);
+    if (explained !== analysis) await fs.promises.writeFile(analysisFile.path, `${JSON.stringify(explained, null, 2)}\n`, "utf8");
+    return explained;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function execute(cfg: any, runOptions: RunOptions): Promise<ExecutionResult> {
+  // Progress is reporting, not execution: a failed update (a registry blip)
+  // must not fail the run it describes. The next update resends the state.
+  const reportProgress = runOptions.onProgress;
+  const options: RunOptions = reportProgress
+    ? {
+      ...runOptions,
+      onProgress: async (progress) => {
+        try {
+          await reportProgress(progress);
+        } catch (error) {
+          console.warn(`[Bugmole] Progress update failed: ${error instanceof Error ? error.message : error}`);
+        }
+      },
+    }
+    : runOptions;
+  try {
+    const { planId, journeyId } = options;
+    const specDir = cfg.runtime.spec_dir || "./spec";
+    const artifactsDir = cfg.runtime.artifacts_dir || "./runs";
+    const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
+    const plansDir = path.join(specDir, "plans");
+
+    // Generate run ID
+    const runId = options.runId ?? `${cfg.runtime.run_id_prefix || "run"}_${Date.now()}`;
+    const startedAt = new Date().toISOString();
+
+    // Load plan - handle both journey ID and full paths
+    let planPath: string;
+
+    // If planId is already a full path, use it directly
+    if (path.isAbsolute(planId) || planId.includes("/") || planId.includes("\\")) {
+      // It's a path - try to resolve it
+      if (path.isAbsolute(planId)) {
+        planPath = planId;
+      } else {
+        // Relative path - try multiple locations
+        const possiblePaths = [
+          path.join(specDir, planId),
+          path.join(plansDir, planId),
+          planId, // Try as-is
+        ];
+
+        // Also try with .flow.yaml extension if not present
+        if (!planId.endsWith(".yaml") && !planId.endsWith(".yml")) {
+          possiblePaths.push(
+            path.join(plansDir, `${planId}.flow.yaml`),
+            path.join(specDir, `${planId}.flow.yaml`),
+            path.join(plansDir, `${planId}.yaml`), // Also try without .flow prefix
+            path.join(specDir, `${planId}.yaml`),
+          );
+        } else {
+          // If it already has .yaml extension, also try with .flow.yaml
+          const baseName = planId.replace(/\.(yaml|yml)$/, "");
+          possiblePaths.push(
+            path.join(plansDir, `${baseName}.flow.yaml`),
+            path.join(specDir, `${baseName}.flow.yaml`),
+          );
+        }
+
+        // Try project directory from environment
+        const projectDirs = [
+          process.env.CURSOR_PROJECT_DIRECTORY,
+          process.env.BUGMOLE_PROJECT_DIR,
+        ].filter(Boolean);
+
+        for (const projectDir of projectDirs) {
+          if (projectDir) {
+            const projectSpecDir = path.join(projectDir, "spec");
+            const projectPlansDir = path.join(projectSpecDir, "plans");
+            possiblePaths.push(
+              path.join(projectSpecDir, planId),
+              path.join(projectPlansDir, planId),
+            );
+            if (!planId.endsWith(".yaml") && !planId.endsWith(".yml")) {
+              possiblePaths.push(
+                path.join(projectPlansDir, `${planId}.flow.yaml`),
+                path.join(projectPlansDir, `${planId}.yaml`), // Also try without .flow
+              );
+            } else {
+              // If it already has .yaml extension, also try with .flow.yaml
+              const baseName = planId.replace(/\.(yaml|yml)$/, "");
+              possiblePaths.push(path.join(projectPlansDir, `${baseName}.flow.yaml`));
+            }
+          }
+        }
+
+        // Additional fallback: if we're in ai-qa-framework, try to find neko-coffee in nested paths
+        if (process.cwd().includes("ai-qa-framework")) {
+          const parentDir = path.dirname(process.cwd());
+          const commonProjectNames = ["neko-coffee", "kive", "neko-coffee-pos"];
+
+          // Try nested paths like Projects/kive/neko-coffee
+          for (const projectName of commonProjectNames) {
+            const kiveDir = path.join(parentDir, "kive");
+            if (fs.existsSync(kiveDir)) {
+              const potentialProjectDir = path.join(kiveDir, projectName);
+              if (fs.existsSync(potentialProjectDir)) {
+                const projectPlansDir = path.join(potentialProjectDir, "spec", "plans");
+                possiblePaths.push(path.join(projectPlansDir, planId));
+                if (!planId.endsWith(".yaml") && !planId.endsWith(".yml")) {
+                  possiblePaths.push(
+                    path.join(projectPlansDir, `${planId}.yaml`),
+                    path.join(projectPlansDir, `${planId}.flow.yaml`),
+                  );
+                } else {
+                  const baseName = planId.replace(/\.(yaml|yml)$/, "");
+                  possiblePaths.push(
+                    path.join(projectPlansDir, `${baseName}.yaml`),
+                    path.join(projectPlansDir, `${baseName}.flow.yaml`),
+                  );
+                }
+              }
+            }
+          }
+        }
+
+        // Find first existing path
+        planPath = possiblePaths.find((p) => fs.existsSync(p)) || possiblePaths[0];
+      }
+    } else {
+      // It's just a journey ID - try both .yaml and .flow.yaml
+      const possiblePaths = [
+        path.join(plansDir, `${planId}.yaml`),
+        path.join(plansDir, `${planId}.flow.yaml`),
+        path.join(specDir, "plans", `${planId}.yaml`),
+        path.join(specDir, "plans", `${planId}.flow.yaml`),
+      ];
+
+      // Try project directory from environment
+      const projectDirs = [
+        process.env.CURSOR_PROJECT_DIRECTORY,
+        process.env.BUGMOLE_PROJECT_DIR,
+      ].filter(Boolean);
+
+      for (const projectDir of projectDirs) {
+        if (projectDir) {
+          const projectPlansDir = path.join(projectDir, "spec", "plans");
+          possiblePaths.push(
+            path.join(projectPlansDir, `${planId}.yaml`),
+            path.join(projectPlansDir, `${planId}.flow.yaml`),
+          );
+        }
+      }
+
+      // Additional fallback: if we're in ai-qa-framework, try to find neko-coffee in nested paths
+      if (process.cwd().includes("ai-qa-framework")) {
+        const parentDir = path.dirname(process.cwd());
+        const commonProjectNames = ["neko-coffee", "kive", "neko-coffee-pos"];
+
+        // Try nested paths like Projects/kive/neko-coffee
+        for (const projectName of commonProjectNames) {
+          const kiveDir = path.join(parentDir, "kive");
+          if (fs.existsSync(kiveDir)) {
+            const potentialProjectDir = path.join(kiveDir, projectName);
+            if (fs.existsSync(potentialProjectDir)) {
+              const projectPlansDir = path.join(potentialProjectDir, "spec", "plans");
+              possiblePaths.push(
+                path.join(projectPlansDir, `${planId}.yaml`),
+                path.join(projectPlansDir, `${planId}.flow.yaml`),
+              );
+            }
+          }
+        }
+      }
+
+      // Find first existing path
+      planPath = possiblePaths.find((p) => fs.existsSync(p)) || possiblePaths[0];
+    }
+
+    const storedPlan = fs.existsSync(planPath) ? undefined : await readStoredPlan(store, cfg.project?.id ?? "default", planId);
+    if (!fs.existsSync(planPath) && storedPlan === undefined) {
+      return {
+        status: "error",
+        runId,
+        journeyId: journeyId || "unknown",
+        stepsExecuted: 0,
+        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"}`,
+      };
+    }
+
+    const planContent = storedPlan ?? fs.readFileSync(planPath, "utf-8");
+    const plan = YAML.parse(planContent);
+
+    // Find journey to execute
+    let journey: any = null;
+    for (const suite of plan.suites || []) {
+      for (const j of suite.journeys || []) {
+        if (!journeyId || j.id === journeyId) {
+          journey = j;
+          break;
+        }
+      }
+      if (journey) break;
+    }
+
+    if (!journey) {
+      return {
+        status: "error",
+        runId,
+        journeyId: journeyId || "unknown",
+        stepsExecuted: 0,
+        stepsPassed: 0,
+        stepsFailed: 0,
+        error: `Journey not found: ${journeyId || "in plan"}`,
+      };
+    }
+
+    const driverId = journey.driver || plan.driver || cfg.execution?.driver || "maestro";
+    const platform = (journey.platform || plan.platform || cfg.project?.platform || "web") as DriverPlatform;
+    const flowReference = journey.flow || plan.flow;
+    let driverResult: Awaited<ReturnType<AppDriver["run"]>>;
+    let driver: AppDriver | undefined;
+    let recoveryAttempts = 0;
+    let targetResults: TargetResult[] | undefined;
+    let fixApplied: ExecutionResult["fixApplied"];
+    let fixError: string | undefined;
+    // Artifacts to upload, with the per-target folder they belong under.
+    let targetArtifacts: Array<{ targetId?: string; artifact: Awaited<ReturnType<AppDriver["run"]>>["artifacts"][number] }> = [];
+    if (driverId === "simulation") {
+      driverResult = {
+        status: "blocked",
+        message: "Simulation is available only as an explicit test driver.",
+        artifacts: [],
+        failureCode: "simulation_driver",
+      };
+    } else if (!flowReference) {
+      driverResult = {
+        status: "blocked",
+        message: `Driver "${driverId}" requires a flow reference.`,
+        artifacts: [],
+        failureCode: "missing_flow",
+      };
+    } else {
+      driver = (options.driverFactory ?? configuredDriver)(cfg, driverId);
+      const target = journey.target || plan.target || {};
+      const localFlowPath = path.isAbsolute(flowReference)
+        ? flowReference
+        : path.resolve(specDir, flowReference);
+      const flowPath = await resolveFlowPath(store, cfg.project?.id ?? "default", runId, artifactsDir, flowReference, localFlowPath);
+      if (options.applyFix) {
+        try {
+          const original = await fs.promises.readFile(flowPath, "utf8");
+          if (options.applyFix.mode === "ai") {
+            if (!options.applyFix.failureContext) throw new Error("the earlier run has no failure details to repair from.");
+            const caller = modelCaller(cfg, { projectId: cfg.project?.id ?? "default", runId, targetId: options.applyFix.targetId });
+            if (!caller) throw new Error("no AI model is available: connect a model key or Bugmole AI.");
+            await options.onProgress?.({ currentStep: "Asking AI for a fix", stepsExecuted: 0, stepsPassed: 0, stepsFailed: 0 });
+            const reply = await caller(repairPrompt(original, options.applyFix.failureContext, options.applyFix.analysis), "repair");
+            const proposed = parseRepair(reply.text, original);
+            if (!proposed) throw new Error("AI couldn't propose a change that passes the flow checks; the app may be at fault.");
+            options.applyFix = { ...options.applyFix, changes: proposed.changes };
+          }
+          if (options.applyFix.changes.length === 0) throw new Error("the earlier run has no suggested fix to apply.");
+          const updated = applyFlowChanges(original, options.applyFix.changes);
+          await fs.promises.writeFile(flowPath, updated, "utf8");
+          // When the plan lists one node per flow step, keep that list in step
+          // with the fixed flow, so results still line up step by step.
+          const stepsBefore = parseMaestroStyleFlow(original, "http://localhost").steps.length;
+          const fixedSteps = parseMaestroStyleFlow(updated, "http://localhost").steps;
+          if (Array.isArray(journey.steps) && journey.steps.length === stepsBefore) {
+            journey.steps = syncPlanSteps(journey.steps, options.applyFix.changes, fixedSteps);
+            const planText = YAML.stringify(plan);
+            if (storedPlan === undefined) await fs.promises.writeFile(planPath, planText, "utf8");
+            else await store.put(`${projectPrefix(cfg.project?.id ?? "default")}/plans/${planId}.flow.yaml`, planText, "text/yaml");
+          }
+          // Keep the stored copy in step, so every worker runs the fixed flow.
+          if (!path.isAbsolute(flowReference)) {
+            const storedKey = `${projectPrefix(cfg.project?.id ?? "default")}/spec/${flowReference.replaceAll("\\", "/").replace(/^\/+/, "")}`;
+            if (flowPath !== localFlowPath || await store.has(storedKey).catch(() => false)) {
+              await store.put(storedKey, updated, "text/yaml");
+            }
+          }
+          fixApplied = { sourceRunId: options.applyFix.sourceRunId, targetId: options.applyFix.targetId, flow: flowReference };
+          await options.onProgress?.({
+            currentStep: options.applyFix.mode === "ai" ? "Applied the AI fix" : "Applied the suggested fix",
+            stepsExecuted: 0,
+            stepsPassed: 0,
+            stepsFailed: 0,
+          });
+        } catch (error) {
+          fixError = error instanceof Error ? error.message : String(error);
+        }
+      }
+      const driverContext = {
+        runId,
+        projectId: cfg.project?.id ?? "default",
+        journeyId: journey.id,
+        flowPath,
+        platform,
+        target: {
+          baseUrl: options.baseUrl || target.base_url || target.baseUrl,
+          appId: target.app_id || target.appId,
+          deviceId: target.device_id || target.deviceId,
+          serial: target.serial,
+        },
+        timeoutMs: cfg.execution?.maestro?.timeout_ms ?? 300_000,
+        artifactsDir,
+        rebaseOrigin: Boolean(options.baseUrl),
+      };
+      // Bracket the whole run (including recovery retries) with a real
+      // device screen recording, so the video reflects the actual attempt
+      // that was graded rather than a separately-timed replay.
+      const videoBasePath = path.join(artifactsDir, cfg.project?.id ?? "default", runId, "run.mp4");
+      const recordingOptions = {
+        chunkSeconds: cfg.execution?.recording?.chunk_seconds,
+        // Off unless asked for: dropping frames makes the video shorter than
+        // the run it records, which is only what you want when you already
+        // know you are looking for the moments something moved.
+        skipIdle: cfg.execution?.recording?.skip_idle === true,
+      };
+      // iOS has no screenrecord, so it is recorded from WebDriverAgent's MJPEG
+      // server instead — the same runner already driving input. It records
+      // only where WDA is actually running, which is the same condition that
+      // makes an iOS run drivable at all.
+      // Device clouds record their own sessions; local recording only applies to local devices.
+      const onlyCloudTargets = Boolean(options.targets?.length) && options.targets!.every((target) => target.cloud);
+      const androidRecording = platform === "android" && driverContext.target.serial && !onlyCloudTargets
+        ? await startAndroidScreenRecording(driverContext.target.serial, "adb", recordingOptions)
+        : undefined;
+      const iosRecording = platform === "ios" && !onlyCloudTargets
+        ? await startIosScreenRecording(videoBasePath, recordingOptions)
+        : undefined;
+      // Collapsed to one shape here rather than shared through the recorders:
+      // Android pulls chunks off the device at stop and needs the destination
+      // then, while iOS has been writing to it all along.
+      const stopRecording: (() => Promise<string[]>) | undefined =
+        androidRecording ? () => androidRecording.stop(videoBasePath)
+        : iosRecording ? () => iosRecording.stop()
+        : undefined;
+      const recoveryPolicy = journey.recovery || plan.recovery || cfg.execution?.recovery;
+      const matrixConfigured = Array.isArray(cfg.execution?.playwright?.browsers) || Array.isArray(cfg.execution?.playwright?.devices);
+      // Device-cloud targets run any flow on real devices; browser targets only apply to web flows.
+      const cloudTargets = options.targets?.filter((target) => target.cloud) ?? [];
+      const runTargets = driverId === "playwright" && platform === "web"
+        ? (options.targets?.length ? options.targets : matrixConfigured ? defaultTargets(cfg) : [])
+        : cloudTargets;
+      const deviceDriver = runTargets.some((target) => target.cloud)
+        ? (options.driverFactory ? options.driverFactory(cfg, "appium") : new AppiumDriver({ access: options.deviceClouds }))
+        : undefined;
+      if (fixError) {
+        driverResult = {
+          status: "blocked",
+          message: `The suggested fix could not be applied: ${fixError}`,
+          artifacts: [],
+          failureCode: "fix_not_applicable",
+        };
+      } else if (runTargets.length > 0) {
+        const activeDriver = driver;
+        const live = runTargets.map(queuedTargetResult);
+        // Lanes report concurrently; updates are chained so they reach the
+        // registry in order.
+        let reporting: Promise<void> = Promise.resolve();
+        const report = (currentStep: string) => {
+          const snapshot = live.map((entry) => ({ ...entry }));
+          reporting = reporting.then(() => options.onProgress?.({
+            currentStep,
+            stepsExecuted: 0,
+            stepsPassed: 0,
+            stepsFailed: 0,
+            targetResults: snapshot,
+          }));
+          return reporting;
+        };
+        await report(`Starting ${runTargets.length} ${runTargets.length === 1 ? "target" : "targets"}`);
+        const outcomes = await runPool(
+          runTargets,
+          resolveTargetConcurrency(cfg.execution?.playwright?.parallel, runTargets.length),
+          async (runTarget, index) => {
+            const startedAtMs = Date.now();
+            live[index] = { ...live[index], status: "running", startedAt: new Date(startedAtMs).toISOString() };
+            await report(`Running on ${targetLabel(runTarget)}`);
+            const context = { ...driverContext, runTarget };
+            const laneDriver = runTarget.cloud && deviceDriver ? deviceDriver : activeDriver;
+            let result: Awaited<ReturnType<AppDriver["run"]>>;
+            let attempts = 0;
+            try {
+              result = await laneDriver.run(context);
+              const recovered = await recoverDriverFailure(laneDriver, context, result, recoveryPolicy);
+              result = recovered.result;
+              attempts = recovered.attempts;
+            } catch (error) {
+              result = {
+                status: "failed",
+                message: error instanceof Error ? error.message : String(error),
+                artifacts: [],
+                failureCode: "driver_error",
+              };
+            }
+            const analysis = result.status === "failed"
+              ? await refineAnalysis(cfg, result, { projectId: cfg.project?.id ?? "default", runId, targetId: runTarget.id })
+              : undefined;
+            const counts = stepCounts(result);
+            live[index] = {
+              ...live[index],
+              status: result.status,
+              completedAt: new Date().toISOString(),
+              durationMs: result.durationMs ?? Date.now() - startedAtMs,
+              stepsPassed: counts.stepsPassed,
+              stepsFailed: counts.stepsFailed,
+              ...(result.failureCode ? { failureCode: result.failureCode } : {}),
+              message: result.message,
+              recoveryAttempts: attempts,
+              ...(result.steps ? {
+                steps: result.steps.map((step) => ({
+                  index: step.sequenceNumber,
+                  status: step.status,
+                  ...(step.label ? { label: step.label } : {}),
+                  ...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
+                  ...(step.status === "failed" && step.message ? { message: step.message } : {}),
+                })),
+              } : {}),
+              ...(analysis ? {
+                analysis: {
+                  title: analysis.title,
+                  category: analysis.category,
+                  source: analysis.source,
+                  ...(analysis.suggestedFix ? { fixSummary: analysis.suggestedFix.summary } : {}),
+                },
+              } : {}),
+            };
+            await report(`${targetLabel(runTarget)} ${result.status}`);
+            return { target: runTarget, result, attempts };
+          },
+        );
+        driverResult = aggregateTargetResults(outcomes);
+        recoveryAttempts = outcomes.reduce((total, outcome) => total + outcome.attempts, 0);
+        targetArtifacts = outcomes.flatMap(({ target: runTarget, result }) =>
+          result.artifacts.map((artifact) => ({ targetId: runTarget.id, artifact })));
+        targetResults = live;
+      } else {
+        driverResult = await driver.run(driverContext);
+        const recovery = await recoverDriverFailure(driver, driverContext, driverResult, recoveryPolicy);
+        driverResult = recovery.result;
+        recoveryAttempts = recovery.attempts;
+      }
+      if (stopRecording) {
+        // One artifact per chunk: screenrecord stops itself at three minutes,
+        // so a longer run is several files rather than a truncated one.
+        const videoPaths = await stopRecording();
+        if (videoPaths.length > 0) {
+          driverResult = {
+            ...driverResult,
+            artifacts: [
+              ...driverResult.artifacts,
+              ...videoPaths.map((videoPath) => ({
+                path: videoPath,
+                contentType: "video/mp4",
+                name: path.basename(videoPath),
+              })),
+            ],
+          };
+        }
+      }
+    }
+
+    if (!targetResults) targetArtifacts = driverResult.artifacts.map((artifact) => ({ artifact }));
+    const results: ExecutionResult["results"] = [];
+    const driverArtifactKeys: RunManifest["artifacts"] = [];
+    let stepsPassed = 0;
+    let stepsFailed = 0;
+
+    // Real per-step data only stands in for the aggregate driver verdict when
+    // its cardinality matches the plan's declared steps: journey.steps is an
+    // authored abstraction (node_id/action/proofs) while driverResult.steps
+    // is Maestro's literal flow-file command sequence, and the two do not
+    // share a vocabulary. A length match is the only case where a positional
+    // correspondence is defensible; otherwise every step would silently
+    // inherit a status attributed to the wrong action.
+    const journeySteps = journey.steps || [];
+    const perStepResults = driverResult.steps;
+    const hasReliableStepCorrespondence =
+      !!perStepResults && perStepResults.length === journeySteps.length;
+
+    for (const step of journeySteps) {
+      const nodeStartedAt = new Date().toISOString();
+      const nodeId = step.node_id || `step:${results.length + 1}`;
+      await options.onProgress?.({
+        currentStep: step.action || "unknown",
+        stepsExecuted: results.length,
+        stepsPassed,
+        stepsFailed,
+      });
+      let screenshot: JourneyScreenshotEvidence | undefined;
+      if (options.captureScreenshot) {
+        await options.onProgress?.({
+          currentStep: `Capturing screenshot: ${step.action || nodeId}`,
+          stepsExecuted: results.length,
+          stepsPassed,
+          stepsFailed,
+        });
+        try {
+          const bytes = await options.captureScreenshot(nodeId, step.action || "unknown");
+          const artifactKey = journeyScreenshotKey(cfg.project?.id ?? "default", journey.id, nodeId);
+          await store.put(artifactKey, bytes, "image/png");
+          screenshot = {
+            source: "runtime",
+            status: "captured",
+            artifactKey,
+            contentType: "image/png",
+            capturedAt: new Date().toISOString(),
+          };
+        } catch (error) {
+          screenshot = {
+            source: "runtime",
+            status: "blocked",
+            reason: error instanceof Error ? error.message : "Runtime screenshot capture failed",
+          };
+        }
+      }
+      const stepIndex = results.length;
+      const observedStep = hasReliableStepCorrespondence ? perStepResults![stepIndex] : undefined;
+      const outcome = observedStep
+        ? observedStep.status === "passed"
+          ? "PASS"
+          : observedStep.status === "failed"
+            ? "FAIL"
+            : "UNKNOWN"
+        : driverResult.status === "passed"
+          ? "PASS"
+          : driverResult.status === "failed"
+            ? "FAIL"
+            : "UNKNOWN";
+      const nodeStatus: NodeExecutionResult["status"] =
+        outcome === "PASS" ? "success" : outcome === "FAIL" ? "failed" : "blocked";
+      const reason: NodeExecutionResult["reason"] = observedStep
+        ? {
+            code: outcome === "PASS" ? "verified" : outcome === "FAIL" ? "execution_failed" : "verification_blocked",
+            message: observedStep.message ?? `Observed driver step status: ${observedStep.status}.`,
+            details: { driver: driverId, platform, durationMs: observedStep.durationMs },
+          }
+        : outcome === "PASS"
+          ? {
+              code: "aggregate_only",
+              message: "The overall driver run passed; this step was not independently verified.",
+            }
+          : outcome === "FAIL"
+            ? {
+                code: "aggregate_only",
+                message: "The overall driver run failed; this step was not independently verified.",
+              }
+            : {
+                code: driverResult.failureCode || "verification_blocked",
+                message: driverResult.message,
+                details: { driver: driverId, platform, exitCode: driverResult.exitCode },
+              };
+      const node: NodeExecutionResult = {
+        nodeId,
+        action: step.action || "unknown",
+        status: nodeStatus,
+        reason,
+        proofs: step.proofs || [],
+        startedAt: observedStep?.timestamp ?? nodeStartedAt,
+        completedAt: observedStep?.timestamp ?? new Date().toISOString(),
+        screenshot,
+      };
+      results.push({
+        nodeId,
+        step: step.action || "unknown",
+        action: step.action || "unknown",
+        outcome,
+        proofs: step.proofs || [],
+        status: node.status,
+        reason: node.reason,
+        startedAt: node.startedAt,
+        completedAt: node.completedAt,
+        screenshot: node.screenshot,
+      });
+      await options.onProgress?.({
+        currentStep: step.action || "unknown",
+        stepsExecuted: results.length,
+        stepsPassed,
+        stepsFailed,
+        node,
+      });
+
+      if (outcome === "PASS") stepsPassed++;
+      else if (outcome === "FAIL") stepsFailed++;
+    }
+
+    // Without a positional match every plan step inherits the aggregate
+    // verdict, so one failed command would read as "11 failed". The driver's
+    // own step list is the honest count whenever it exists.
+    if (!hasReliableStepCorrespondence && perStepResults?.length) {
+      ({ stepsPassed, stepsFailed } = stepCounts(driverResult));
+    }
+
+    for (const { targetId, artifact } of targetArtifacts) {
+      try {
+        const contents = await fs.promises.readFile(artifact.path);
+        const name = artifact.name || path.basename(artifact.path);
+        const artifactKey = runKey(
+          cfg.project?.id ?? "default",
+          runId,
+          targetId ? `artifacts/${targetId}/${name}` : `artifacts/${name}`,
+        );
+        await store.put(
+          artifactKey,
+          contents,
+          artifact.contentType || "application/octet-stream",
+        );
+        driverArtifactKeys.push({ key: artifactKey, contentType: artifact.contentType });
+        const entry = targetId ? targetResults?.find((candidate) => candidate.targetId === targetId) : undefined;
+        if (entry) {
+          entry.artifactKeys.push(artifactKey);
+          if (name === "playwright-final.png" || name === "playwright-failure.png") entry.finalScreenshotKey = artifactKey;
+          if (name === "playwright.log") entry.logKey = artifactKey;
+          if (name === "playwright-trace.zip") entry.traceKey = artifactKey;
+          if (name === "analysis.json") entry.analysisKey = artifactKey;
+          // Playwright's web recording always uses this name; a device's screen
+          // recording (iOS/Android) is named after its own chunked video file
+          // instead, so match by content type for that case. First video wins:
+          // a device recording that screenrecord split into several chunks
+          // keeps its later parts reachable via artifactKeys, but the run
+          // detail view plays the first one.
+          if ((name === "playwright-run.webm" || artifact.contentType?.startsWith("video/")) && !entry.videoKey) entry.videoKey = artifactKey;
+        }
+      } catch {
+        // Driver output remains diagnostic even if an optional artifact cannot be uploaded.
+      }
+    }
+
+    // Save execution results
+    const completedAt = new Date().toISOString();
+    const resultsKey = runKey(cfg.project?.id ?? "default", runId, "results.json");
+    await store.put(resultsKey, json({
+      runId,
+      journeyId: journey.id,
+      driver: driverId,
+      platform,
+      failureCode: driverResult.failureCode,
+      recoveryAttempts,
+      planId,
+      timestamp: completedAt,
+      ...(targetResults ? { baseUrl: options.baseUrl, targets: targetResults } : {}),
+      results,
+    }), "application/json");
+    const manifest: RunManifest = {
+      version: 1,
+      projectId: cfg.project?.id ?? "default",
+      tenantId: cfg.project?.tenant,
+      environmentId: cfg.project?.environment ?? cfg.runtime.env,
+      runId,
+      planId,
+      journeyId: journey.id,
+      status: stepsFailed === 0 && !results.some((result) => result.status === "blocked") ? "success" : "partial",
+      startedAt,
+      completedAt,
+      stepsExecuted: results.length,
+      stepsPassed,
+      stepsFailed,
+      artifacts: [{ key: resultsKey, contentType: "application/json" }, ...driverArtifactKeys],
+      ...(targetResults ? { targets: targetResults } : {}),
+    };
+    const manifestKey = runKey(manifest.projectId, runId, "manifest.json");
+    await store.put(manifestKey, json(manifest), "application/json");
+
+    return {
+      status: stepsFailed === 0 && !results.some((result) => result.status === "blocked") ? "success" : "partial",
+      runId,
+      journeyId: journey.id,
+      stepsExecuted: results.length,
+      stepsPassed,
+      stepsFailed,
+      driver: driverId,
+      platform,
+      recoveryAttempts,
+      failureCode: driverResult.failureCode,
+      evidencePath: runPrefix(manifest.projectId, runId),
+      manifestKey,
+      message: targetResults
+        ? `Execution completed on ${targetResults.length} target(s). ${driverResult.message}`
+        : `Execution completed. ${stepsPassed} passed, ${stepsFailed} failed.`,
+      ...(targetResults ? { targetResults } : {}),
+      durationMs: Date.parse(completedAt) - Date.parse(startedAt),
+      ...(fixApplied ? { fixApplied } : {}),
+      results,
+    };
+  } catch (error: any) {
+    return {
+      status: "error",
+      runId: `error_${Date.now()}`,
+      journeyId: options.journeyId || "unknown",
+      stepsExecuted: 0,
+      stepsPassed: 0,
+      stepsFailed: 0,
+      error: error.message || "Execution failed",
+    };
+  }
+}
+