@qawolf/cli 1.3.0 → 1.4.0

package/dist/cli.js

@@ -8514,7 +8514,7 @@ var require_BufferList = __commonJS((exports, module) => {
       this.head = this.tail = null;
       this.length = 0;
     };
-    BufferList.prototype.join = function join32(s3) {
+    BufferList.prototype.join = function join33(s3) {
       if (this.length === 0)
         return "";
       var p3 = this.head;
@@ -23070,7 +23070,7 @@ var require_BufferList2 = __commonJS((exports, module) => {
       this.head = this.tail = null;
       this.length = 0;
     };
-    BufferList.prototype.join = function join32(s3) {
+    BufferList.prototype.join = function join33(s3) {
       if (this.length === 0)
         return "";
       var p3 = this.head;
@@ -155181,7 +155181,7 @@ var authMessages = {
       rejected403: (noun) => `QA Wolf API rejected the${noun ? ` ${noun}` : ""} request (HTTP 403). Check that your API key has access to this environment.`,
       notFound404: (noun) => `QA Wolf API could not find ${noun ? `${noun} for that environment` : "that environment"} (HTTP 404). Check the --env value.`,
       failedWithStatus: (status, noun) => `QA Wolf API${noun ? ` ${noun}` : ""} request failed (HTTP ${status}).`,
-      networkUnreachable: (baseUrl, noun) => `Could not reach the QA Wolf API at ${baseUrl}${noun ? ` to fetch ${noun}` : ""}. Check your network connection and QAWOLF_API_URL.`,
+      networkUnreachable: (baseUrl, noun) => `Could not reach the QA Wolf API at ${baseUrl}${noun ? ` to fetch ${noun}` : ""}. Check your network connection and QAWOLF_HOST_URL.`,
       unexpectedResponse: (noun) => `Unexpected${noun ? ` ${noun}` : ""} response from the QA Wolf API.`
     },
     bundle: {
@@ -155626,6 +155626,15 @@ function makeDefaultFs() {
   };
 }
 
+// src/shell/resolveHostUrl.ts
+var defaultHostUrl = "https://app.qawolf.com";
+function resolveHostUrl(env2) {
+  const configuredHostUrl = env2["QAWOLF_HOST_URL"]?.trim();
+  if (!configuredHostUrl)
+    return defaultHostUrl;
+  return configuredHostUrl.replace(/\/+$/, "");
+}
+
 // src/domains/auth/resolve.ts
 import { Entry as Entry3 } from "@napi-rs/keyring";
 
@@ -173377,7 +173386,7 @@ function buildBaseContext(command, signals) {
     logPath: defaultLogPath(),
     ...verboseWrite ? { verboseWrite } : {}
   });
-  const apiBaseUrl = env2["QAWOLF_API_URL"]?.replace(/\/+$/, "") || "https://app.qawolf.com";
+  const apiBaseUrl = resolveHostUrl(env2);
   return {
     ctx: {
       ui: createUI(outputMode, {
@@ -173589,7 +173598,7 @@ function registerAuthCommand(program2, signals) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.3.0",
+  version: "1.4.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -173649,16 +173658,17 @@ var package_default = {
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
     "@playwright/test": "1.60.0",
-    "@qawolf/api-contracts": "0.2.0",
+    "@qawolf/api-contracts": "0.11.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
-    "@qawolf/flows": "0.1.1",
+    "@qawolf/flows": "0.1.4",
     "@qawolf/testkit": "1.1.1",
     appium: "2.11.3",
     "appium-uiautomator2-driver": "3.7.0",
     "appium-xcuitest-driver": "9.10.5",
     commander: "14.0.3",
     "env-paths": "4.0.0",
+    "expect-webdriverio": "5.6.5",
     picomatch: "4.0.4",
     pino: "10.3.1",
     playwright: "1.58.2",
@@ -175132,13 +175142,14 @@ import { createHash } from "node:crypto";
 import { join as join12, resolve as resolve3 } from "node:path";
 
 // src/generated/dependencyVersions.ts
-var flowsVersion = "0.1.1";
+var flowsVersion = "0.1.4";
 var playwrightVersion = "1.58.2";
 var emailsVersion = "1.1.1";
 var testkitVersion = "1.1.1";
 var appiumVersion = "2.11.3";
 var appiumXcuitestDriverVersion = "9.10.5";
 var appiumUiautomator2DriverVersion = "3.7.0";
+var expectWebdriverioVersion = "5.6.5";
 
 // src/domains/runtimeEnv/pinnedPackages.ts
 var pinnedPackages = [
@@ -175151,7 +175162,8 @@ var pinnedPackages = [
   {
     name: "appium-uiautomator2-driver",
     version: appiumUiautomator2DriverVersion
-  }
+  },
+  { name: "expect-webdriverio", version: expectWebdriverioVersion }
 ];
 
 // src/domains/runtimeEnv/managedEnvDir.ts
@@ -175664,9 +175676,125 @@ var import_picomatch2 = __toESM(require_picomatch2(), 1);
 
 // node_modules/@qawolf/api-contracts/dist/v1/ids.js
 var defaultIdSchemas = {
+  automation: exports_external.string().min(1).describe("The id of the automation."),
   environment: exports_external.string().min(1).describe("The id of the environment."),
   flow: exports_external.string().min(1).describe("The id of the flow."),
-  run: exports_external.string().min(1).describe("The id of the run.")
+  issue: exports_external.string().min(1).describe("The id of the issue."),
+  run: exports_external.string().min(1).describe("The id of the run."),
+  workspace: exports_external.string().min(1).describe("The id of the workspace.")
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/resource.js
+function resource(fields, { urlFieldDescription = "Absolute URL." } = {}) {
+  return exports_external.object({
+    ...fields,
+    url: exports_external.url().describe(urlFieldDescription)
+  });
+}
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/flowSelection.js
+var makeFlowSelectionSchema = (ids) => exports_external.object({
+  flowIds: exports_external.array(ids.flow).default([]),
+  tagNames: exports_external.array(exports_external.string().min(1)).default([])
+}).refine((selection) => selection.flowIds.length + selection.tagNames.length > 0, {
+  message: "At least one flow or tag is required."
+});
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/index.js
+var makeCreateRunContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment,
+    environmentVariables: exports_external.record(exports_external.string(), exports_external.string()).optional(),
+    ignoreRules: exports_external.boolean().default(false),
+    pullRequestNumber: exports_external.number().int().positive().describe("The number of the pull request to associate with the run.").optional(),
+    repository: exports_external.string().min(1).describe('The owner/name of the repository, e.g. "acme/web".').optional()
+  }).and(makeFlowSelectionSchema(ids));
+  const output = resource({ runId: ids.run }, { urlFieldDescription: "Absolute URL of the run page." });
+  return {
+    description: "Create a run for the selected flows and/or tags in an environment.",
+    input,
+    kind: "write",
+    name: "run.create",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/automate/index.js
+var makeAutomateContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment,
+    flowIds: exports_external.array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("Draft flows the automation builds."),
+    patch: exports_external.string().min(1).max(1e6).optional().describe("Unified diff applied to the automation's working branch before it runs.")
+  });
+  const output = resource({ automationId: ids.automation }, { urlFieldDescription: "Absolute URL of the automation review page." });
+  return {
+    description: "Request an automation that builds the selected draft flows in an environment.",
+    input,
+    kind: "write",
+    name: "automate",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/environment/index.js
+var makeEnvironmentResource = (environmentId) => resource({
+  environmentId,
+  flowCodeBranch: exports_external.discriminatedUnion("syncStatus", [
+    exports_external.object({
+      lastSyncedCommitHash: exports_external.string().describe("Hash of the latest reconciled commit."),
+      name: exports_external.string().describe("The name of the environment's flow code branch."),
+      syncStatus: exports_external.literal("reconciled").describe("The branch has reconciled at least one commit.")
+    }),
+    exports_external.object({
+      name: exports_external.string().describe("The name of the environment's flow code branch."),
+      syncStatus: exports_external.literal("not-reconciled").describe("The branch has not reconciled any commit yet.")
+    })
+  ]).optional().describe("The environment's flow code branch and its git reconciliation state, if it has one."),
+  kind: exports_external.enum(["static", "preview"]).describe("Whether the environment is static or a preview."),
+  name: exports_external.string(),
+  status: exports_external.enum(["blocked", "needs-investigation", "ready", "running"]).describe("Standing health across the environment's runs: blocked (open blocking bugs), needs-investigation (failures awaiting triage), running (flows executing), ready (none of the above — the greenlit state)."),
+  terminatedAt: exports_external.iso.datetime().optional().describe("When the environment was terminated, if it has been.")
+}, { urlFieldDescription: "Absolute URL of the environment page." });
+var makeGetEnvironmentContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment
+  });
+  const output = makeEnvironmentResource(ids.environment);
+  return {
+    description: "Read a single environment's name, kind, health status, and termination state.",
+    input,
+    kind: "read",
+    name: "environment.get",
+    output
+  };
+};
+var makeListEnvironmentVariableNamesContract = (ids) => {
+  const input = exports_external.object({
+    environmentId: ids.environment
+  });
+  const output = exports_external.object({
+    variableNames: exports_external.array(exports_external.string()).describe("Names of the environment's variables, sorted alphabetically. Values are never returned.")
+  });
+  return {
+    description: "List the names of an environment's variables, sorted. Names only — values never leave the server.",
+    input,
+    kind: "read",
+    name: "environment.listVariableNames",
+    output
+  };
+};
+var makeCreateEnvironmentContract = (ids) => {
+  const input = exports_external.object({
+    name: exports_external.string().min(1).max(255).regex(/\S/, "Environment name cannot be blank.").describe("Display name of the new environment.")
+  });
+  const output = makeEnvironmentResource(ids.environment);
+  return {
+    description: "Create an environment on the caller's team and return it in the environment.get shape.",
+    input,
+    kind: "write",
+    name: "environment.create",
+    output
+  };
 };
 
 // node_modules/@qawolf/api-contracts/dist/v1/flow/index.js
@@ -175677,12 +175805,14 @@ var makeListFlowsContract = (ids) => {
   });
   const executionTarget = exports_external.union([exports_external.string().min(1), exports_external.record(exports_external.string(), exports_external.unknown())]).describe("The target the flow executes against, as a preset or object.");
   const output = exports_external.object({
-    flows: exports_external.array(exports_external.object({
+    flows: exports_external.array(resource({
       executionTarget,
       flowId: ids.flow,
       name: exports_external.string(),
       path: exports_external.string().describe("The flow file path, relative to the repo."),
       tags: exports_external.array(exports_external.string())
+    }, {
+      urlFieldDescription: "Absolute URL of the flow page in its environment."
     }))
   });
   return {
@@ -175694,33 +175824,229 @@ var makeListFlowsContract = (ids) => {
   };
 };
 
-// node_modules/@qawolf/api-contracts/dist/v1/run/index.js
-var makeCreateRunContract = (ids) => {
-  const input = exports_external.object({
+// node_modules/@qawolf/api-contracts/dist/v1/pagination.js
+var makePaginationInputFields = (limits) => ({
+  cursor: exports_external.string().min(1).optional().describe("Opaque cursor copied from the previous response's nextCursor. Omit to fetch the first page."),
+  limit: exports_external.number().int().min(1).max(limits.maxLimit).default(limits.defaultLimit).describe(`Maximum rows per page. Defaults to ${limits.defaultLimit}, capped at ${limits.maxLimit}.`)
+});
+var nextCursorSchema = exports_external.string().min(1).optional().describe("Repeat the request with this value as cursor to fetch the next page. Absent when there are no further results.");
+
+// node_modules/@qawolf/api-contracts/dist/v1/issue/index.js
+var issuePrioritySchema = exports_external.enum([
+  "unprioritized",
+  "low",
+  "medium",
+  "high",
+  "urgent"
+]);
+var issueStatusSchema = exports_external.enum([
+  "pending",
+  "inProgress",
+  "paused",
+  "resolved",
+  "canceled",
+  "archived"
+]);
+var publicIssueTypeSchema = exports_external.enum(["bug", "coverageRequest", "maintenance"]);
+var openIssueStatuses = ["pending", "inProgress", "paused"];
+var makeIssueResourceSchema = (ids) => resource({
+  createdAt: exports_external.coerce.date().describe("When the issue was created."),
+  description: exports_external.string().describe("The issue description in Markdown."),
+  issueId: ids.issue,
+  name: exports_external.string(),
+  number: exports_external.number().int(),
+  priority: issuePrioritySchema,
+  reproductions: exports_external.array(exports_external.object({
     environmentId: ids.environment,
-    environmentVariables: exports_external.record(exports_external.string(), exports_external.string()).optional(),
-    flowIds: exports_external.array(ids.flow).min(1),
-    ignoreRules: exports_external.boolean().default(false)
+    firstReproducedInRunId: ids.run,
+    flowId: ids.flow,
+    isActive: exports_external.boolean(),
+    lastReproducedInRunId: ids.run
+  })).describe("The environments, flows, and runs where the issue was reproduced."),
+  status: issueStatusSchema,
+  type: publicIssueTypeSchema
+}, { urlFieldDescription: "Absolute URL of the issue page." });
+var makeFindIssuesContract = (ids) => {
+  const input = exports_external.object({
+    ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 100 }),
+    statuses: exports_external.array(issueStatusSchema).min(1).default([...openIssueStatuses]).describe("Issue statuses to include. Defaults to pending, in-progress, and paused issues."),
+    type: publicIssueTypeSchema.describe("The issue type to include: bug report, maintenance report, or coverage request.")
+  });
+  const output = exports_external.object({
+    issues: exports_external.array(makeIssueResourceSchema(ids)).describe("The team's bug reports, maintenance reports, or coverage requests, newest first."),
+    nextCursor: nextCursorSchema
+  });
+  return {
+    description: "List the team's bug reports, maintenance reports, or coverage requests, newest first.",
+    input,
+    kind: "read",
+    name: "issue.find",
+    output
+  };
+};
+var makeGetIssueContract = (ids) => {
+  const input = exports_external.object({
+    issueId: ids.issue
+  });
+  const output = exports_external.object({
+    issue: makeIssueResourceSchema(ids)
   });
-  const output = exports_external.object({ runId: ids.run });
   return {
-    description: "Create a run for selected flows in an environment.",
+    description: "Get an issue by id.",
+    input,
+    kind: "read",
+    name: "issue.get",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/issue/create.js
+var makeCreateIssueContract = (ids) => {
+  const commonFields = {
+    description: exports_external.string().optional().describe("The issue description as plain text; each line becomes a paragraph. Markdown is not parsed."),
+    name: exports_external.string().trim().min(1).max(255),
+    priority: issuePrioritySchema.optional().describe('Defaults to "unprioritized".')
+  };
+  const input = exports_external.discriminatedUnion("type", [
+    exports_external.object({
+      ...commonFields,
+      type: exports_external.literal("bug")
+    }),
+    exports_external.object({
+      ...commonFields,
+      estimatedDueDate: exports_external.iso.date().optional().describe("The calendar date the coverage is estimated to be complete, as YYYY-MM-DD."),
+      type: exports_external.literal("coverageRequest")
+    })
+  ]);
+  const output = exports_external.object({
+    issue: makeIssueResourceSchema(ids)
+  });
+  return {
+    description: "Create a bug or coverage request issue for the caller's team. " + "Maintenance issues cannot be created through the public API.",
     input,
     kind: "write",
-    name: "run.create",
+    name: "issue.create",
     output
   };
 };
 
-// node_modules/@qawolf/api-contracts/dist/v1/index.js
-var makeContractsV1 = (ids) => ({
-  flow: {
-    list: makeListFlowsContract(ids)
-  },
-  run: {
-    create: makeCreateRunContract(ids)
-  }
+// node_modules/@qawolf/api-contracts/dist/v1/run/summary.js
+var makeRunSummaryFields = (ids) => ({
+  completedAt: exports_external.iso.datetime().optional().describe("When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped)."),
+  createdAt: exports_external.iso.datetime(),
+  git: exports_external.object({
+    branch: exports_external.string().optional(),
+    commitMessage: exports_external.string().optional(),
+    commitSha: exports_external.string().optional(),
+    commitUrl: exports_external.string().optional().describe("Link to the commit on the code host.")
+  }).describe("The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create."),
+  runId: ids.run,
+  status: exports_external.enum(["queued", "running", "passed", "failed", "canceled"]).describe("Whole-run status. Terminal statuses are passed, failed, and canceled; poll until one is reached.")
+});
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/find.js
+var makeFindRunsContract = (ids) => {
+  const input = exports_external.object({
+    createdAfter: exports_external.iso.datetime({ offset: true }).optional().describe("Only include runs created after this instant, e.g. the runs since a deploy."),
+    ...makePaginationInputFields({ defaultLimit: 20, maxLimit: 100 }),
+    environmentId: ids.environment
+  });
+  const output = exports_external.object({
+    nextCursor: nextCursorSchema,
+    runs: exports_external.array(resource(makeRunSummaryFields(ids), {
+      urlFieldDescription: "Absolute URL of the run page."
+    })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
+  });
+  return {
+    description: "List an environment's recent runs, newest first.",
+    input,
+    kind: "read",
+    name: "run.find",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/get.js
+var makeGetRunContract = (ids) => {
+  const input = exports_external.object({
+    runId: ids.run
+  });
+  const failedFlow = exports_external.object({
+    failure: exports_external.object({
+      error: exports_external.string()
+    }),
+    flowId: ids.flow,
+    name: exports_external.string(),
+    status: exports_external.literal("failed")
+  });
+  const nonFailedFlow = exports_external.object({
+    flowId: ids.flow,
+    name: exports_external.string(),
+    status: exports_external.enum(["queued", "running", "passed", "canceled"])
+  });
+  const flows = exports_external.array(exports_external.discriminatedUnion("status", [failedFlow, nonFailedFlow])).describe("The run's flows, ordered alphabetically by name.");
+  const output = resource({
+    ...makeRunSummaryFields(ids),
+    flows
+  }, { urlFieldDescription: "Absolute URL of the run page." });
+  return {
+    description: "Get a run's status, per-flow results, and links.",
+    input,
+    kind: "read",
+    name: "run.get",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/tag/index.js
+var makeTagResourceSchema = () => resource({
+  color: exports_external.string().regex(/^#[0-9a-fA-F]{6}$/).describe("The tag's display color as a hex code, assigned by QA Wolf."),
+  name: exports_external.string()
+}, {
+  urlFieldDescription: "Absolute URL of the team's tag settings page."
 });
+var makeCreateTagContract = () => {
+  const input = exports_external.object({
+    name: exports_external.string().trim().min(1).max(255).refine((name) => !name.includes(","), "Tag names cannot include commas.")
+  });
+  const output = makeTagResourceSchema();
+  return {
+    description: "Create a tag on the caller's team. Tags select flows in run.create.",
+    input,
+    kind: "write",
+    name: "tag.create",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/index.js
+var makeContractsV1 = (ids) => {
+  const resolvedIds = { ...defaultIdSchemas, ...ids };
+  return {
+    automate: makeAutomateContract(resolvedIds),
+    environment: {
+      create: makeCreateEnvironmentContract(resolvedIds),
+      get: makeGetEnvironmentContract(resolvedIds),
+      listVariableNames: makeListEnvironmentVariableNamesContract(resolvedIds)
+    },
+    flow: {
+      list: makeListFlowsContract(resolvedIds)
+    },
+    issue: {
+      create: makeCreateIssueContract(resolvedIds),
+      find: makeFindIssuesContract(resolvedIds),
+      get: makeGetIssueContract(resolvedIds)
+    },
+    run: {
+      create: makeCreateRunContract(resolvedIds),
+      find: makeFindRunsContract(resolvedIds),
+      get: makeGetRunContract(resolvedIds)
+    },
+    tag: {
+      create: makeCreateTagContract()
+    }
+  };
+};
 var publicContractsV1 = makeContractsV1(defaultIdSchemas);
 
 // src/domains/flows/listRemote.ts
@@ -179728,8 +180054,7 @@ async function dispatchFlow({
     run = { ...run, manifest: stamp };
   const durationMs = deps.now() - flowStart;
   const outcome = run.passed ? "pass" : "fail";
-  const attempts = run.attempts;
-  const attempt = pluralize(attempts, "attempt");
+  const attempt = pluralize(run.attempts, "attempt");
   deps.logger?.info(`${outcome}: ${flow.name} (${durationMs}ms, ${attempt})`);
   return { run, durationMs };
 }
@@ -180059,7 +180384,7 @@ async function defaultRunWebFlowDeps(cwd = process.cwd(), signals) {
 
 // src/domains/runtimeEnv/prepareRunDir.ts
 import { createHash as createHash3 } from "node:crypto";
-import { basename as basename4, dirname as dirname10, join as join28, resolve as resolve8, sep as sep4 } from "node:path";
+import { basename as basename4, dirname as dirname10, join as join29, resolve as resolve8, sep as sep4 } from "node:path";
 
 // src/shell/copyDir.ts
 import { cp, readdir as readdir2 } from "node:fs/promises";
@@ -180100,6 +180425,9 @@ async function readPackageJson(pkgPath, fs3) {
 }
 
 // src/domains/runtimeEnv/innerHop.ts
+import { join as join27 } from "node:path";
+
+// src/domains/runtimeEnv/linkPinnedPackages.ts
 import { dirname as dirname8, join as join26 } from "node:path";
 
 // src/domains/runtimeEnv/symlinkDir.ts
@@ -180109,25 +180437,35 @@ async function createDirSymlink(source, target) {
   await symlink(source, target, linkType);
 }
 
-// src/domains/runtimeEnv/innerHop.ts
-async function populateInnerHop(args) {
-  const { depsRoot, execDir, fs: fs3 } = args;
+// src/domains/runtimeEnv/linkPinnedPackages.ts
+async function linkPinnedPackages(args) {
+  const { depsRoot, nodeModulesDir, fs: fs3 } = args;
   const managedModules = join26(depsRoot, "node_modules");
-  const innerModules = join26(execDir, "node_modules");
-  await fs3.mkdir(innerModules, { recursive: true });
+  await fs3.mkdir(nodeModulesDir, { recursive: true });
   for (const { name } of pinnedPackages) {
     const segments = name.split("/");
-    const target = join26(innerModules, ...segments);
+    const target = join26(nodeModulesDir, ...segments);
     if (segments.length > 1) {
       await fs3.mkdir(dirname8(target), { recursive: true });
     }
+    await fs3.rm(target, { recursive: true, force: true });
     await createDirSymlink(join26(managedModules, ...segments), target);
   }
 }
 
+// src/domains/runtimeEnv/innerHop.ts
+async function populateInnerHop(args) {
+  const { depsRoot, execDir, fs: fs3 } = args;
+  await linkPinnedPackages({
+    depsRoot,
+    nodeModulesDir: join27(execDir, "node_modules"),
+    fs: fs3
+  });
+}
+
 // src/domains/runtimeEnv/outerHop.ts
 import { lstat } from "node:fs/promises";
-import { dirname as dirname9, join as join27 } from "node:path";
+import { dirname as dirname9, join as join28 } from "node:path";
 var executorPackageNames = new Set(pinnedPackages.map((p3) => p3.name));
 async function populateOuterHop(args) {
   const { projectDir, runDir, fs: fs3 } = args;
@@ -180137,23 +180475,28 @@ async function populateOuterHop(args) {
   const depNames = Object.keys(installableDeps);
   const { satisfying, rejected } = await findSatisfyingNodeModulesDir(projectDir, depNames, fs3);
   if (satisfying !== undefined) {
-    await createDirSymlink(satisfying, join27(runDir, "node_modules"));
+    await createDirSymlink(satisfying, join28(runDir, "node_modules"));
     return { mode: "symlink", nodeModulesDir: satisfying };
   }
   if (depNames.length === 0)
     return { mode: "none" };
   args.onInstallStart?.(depNames.length);
   await installOuterDeps(runDir, installableDeps, fs3, args.install ?? spawnNpmInstall);
+  await linkPinnedPackages({
+    depsRoot: args.depsRoot,
+    nodeModulesDir: join28(runDir, "node_modules"),
+    fs: fs3
+  });
   return { mode: "install", depCount: depNames.length, rejected };
 }
 async function findSatisfyingNodeModulesDir(startDir, depNames, fs3) {
   const rejected = [];
   let dir = startDir;
   while (true) {
-    const candidate = join27(dir, "node_modules");
+    const candidate = join28(dir, "node_modules");
     const stats = await lstatSafe(candidate);
     if (stats !== undefined && stats.isDirectory() && !stats.isSymbolicLink()) {
-      const missing = depNames.filter((name) => !fs3.existsSync(join27(candidate, name, "package.json")));
+      const missing = depNames.filter((name) => !fs3.existsSync(join28(candidate, name, "package.json")));
       if (missing.length === 0)
         return { satisfying: candidate, rejected };
       rejected.push({ dir: candidate, missing });
@@ -180174,7 +180517,7 @@ async function lstatSafe(path3) {
 async function readInstallableDeps(projectDir, fs3) {
   let content;
   try {
-    content = await fs3.readFile(join27(projectDir, "package.json"));
+    content = await fs3.readFile(join28(projectDir, "package.json"));
   } catch {
     return {};
   }
@@ -180192,8 +180535,8 @@ async function readInstallableDeps(projectDir, fs3) {
   return Object.fromEntries(Object.entries(rawDeps).filter(([name]) => !executorPackageNames.has(name)).filter((entry) => typeof entry[1] === "string"));
 }
 async function installOuterDeps(runDir, deps, fs3, install) {
-  await fs3.writeFile(join27(runDir, "package.json"), JSON.stringify({ name: "qawolf-run", private: true, dependencies: deps }, undefined, 2));
-  await fs3.writeFile(join27(runDir, ".npmrc"), `@qawolf:registry=https://registry.npmjs.org/
+  await fs3.writeFile(join28(runDir, "package.json"), JSON.stringify({ name: "qawolf-run", private: true, dependencies: deps }, undefined, 2));
+  await fs3.writeFile(join28(runDir, ".npmrc"), `@qawolf:registry=https://registry.npmjs.org/
 `);
   const result = await install(runDir);
   if (result.exitCode !== 0) {
@@ -180207,10 +180550,10 @@ async function prepareRunDir(args) {
   const { files, projectDir, depsRoot, runRoot } = args;
   const fs3 = args.fs ?? makeDefaultFs();
   const runId = buildRunId(projectDir, files);
-  const runDir = join28(runRoot, runId);
+  const runDir = join29(runRoot, runId);
   await fs3.rm(runDir, { recursive: true, force: true });
   await fs3.mkdir(runDir, { recursive: true });
-  const execDir = join28(runDir, "exec");
+  const execDir = join29(runDir, "exec");
   await fs3.mkdir(execDir, { recursive: true });
   await populateInnerHop({ depsRoot, execDir, fs: fs3 });
   const stagedFiles = await stageFlowFiles({ files, projectDir, execDir, fs: fs3 });
@@ -180220,6 +180563,7 @@ async function prepareRunDir(args) {
   const outerHop = await populateOuterHop({
     projectDir,
     runDir,
+    depsRoot,
     fs: fs3,
     ...args.onInstallStart !== undefined ? { onInstallStart: args.onInstallStart } : {}
   });
@@ -180247,37 +180591,37 @@ async function stageFlowFiles(args) {
   if (files.length > 1) {
     return Promise.all(files.map(async (f3) => {
       const dirHash = createHash3("sha256").update(dirname10(f3)).digest("hex").slice(0, 8);
-      const subDir = join28(execDir, dirHash);
+      const subDir = join29(execDir, dirHash);
       await fs3.mkdir(subDir, { recursive: true });
-      const dest = join28(subDir, basename4(f3));
+      const dest = join29(subDir, basename4(f3));
       await fs3.copyFile(f3, dest);
       return dest;
     }));
   }
-  await Promise.all(files.map((f3) => fs3.copyFile(f3, join28(execDir, basename4(f3)))));
-  return files.map((f3) => join28(execDir, basename4(f3)));
+  await Promise.all(files.map((f3) => fs3.copyFile(f3, join29(execDir, basename4(f3)))));
+  return files.map((f3) => join29(execDir, basename4(f3)));
 }
 function remapPath(file2, projectDir, execDir) {
   if (file2 === projectDir)
     return execDir;
   if (file2.startsWith(projectDir + sep4)) {
-    return join28(execDir, file2.slice(projectDir.length + 1));
+    return join29(execDir, file2.slice(projectDir.length + 1));
   }
   return file2;
 }
 
 // src/shell/testkit.ts
-import { join as join29 } from "node:path";
+import { join as join30 } from "node:path";
 function notAvailableLocally(name) {
   throw new Error(runnerMessages.notAvailableLocally(name));
 }
 async function loadSdkDeps(cwd) {
-  const testkitDir = join29(cwd, "node_modules", "@qawolf", "testkit");
+  const testkitDir = join30(cwd, "node_modules", "@qawolf", "testkit");
   try {
     const clientMod = await import(resolveFromEnvDir(cwd, "@qawolf/testkit/client"));
     if (typeof clientMod.createTestkitClient !== "function")
       throw new Error("createTestkitClient is not a function");
-    const scopeMod = await import(join29(testkitDir, "dist", "clientScope.js"));
+    const scopeMod = await import(join30(testkitDir, "dist", "clientScope.js"));
     if (typeof scopeMod.configureTestkitClient !== "function")
       throw new Error("configureTestkitClient is not a function");
     return {
@@ -180334,9 +180678,9 @@ async function registerLazyEmailsClient(getInbox, cwd, deps) {
 }
 
 // src/commands/flows/envVarDeps.ts
-import { join as join30 } from "node:path";
+import { join as join31 } from "node:path";
 function envFilePath(envDir) {
-  return join30(envDir, ".env");
+  return join31(envDir, ".env");
 }
 async function readEnv(envDir, fs3) {
   try {
@@ -180445,7 +180789,7 @@ async function createFlowRuntimeDeps({
 }
 
 // src/shell/appium/createAppiumServer.ts
-import { join as join31 } from "node:path";
+import { join as join32 } from "node:path";
 
 // src/shell/appium/spawnAppium.ts
 import { spawn as spawn2 } from "node:child_process";
@@ -180520,7 +180864,7 @@ async function createAppiumServer(envDir, signals, params) {
   const spawnFn = params?.deps?.spawn ?? defaultSpawnAppium;
   const findFreePortFn = params?.deps?.findFreePort ?? findFreePort;
   const resolveAppiumBinFn = params?.deps?.resolveAppiumBin ?? resolveAppiumBin;
-  const appiumHome2 = params?.options?.appiumHome ?? join31(envPaths("qawolf").data, "appium");
+  const appiumHome2 = params?.options?.appiumHome ?? join32(envPaths("qawolf").data, "appium");
   const timeoutMs3 = params?.options?.startTimeoutMs ?? defaultStartTimeoutMs;
   const bin = resolveAppiumBinFn(envDir);
   const port = await findFreePortFn();
@@ -180892,7 +181236,7 @@ async function installBrowserList(ctx, browsers, deps) {
   await ctx.ui.withProgress(browsers.map((browser) => ({
     message: installMessages.installingBrowser(browser),
     task: async () => {
-      const args = buildArgs(browser, deps.platform);
+      const args = buildArgs(browser, deps.platform, deps.browserDeps);
       const result = await deps.spawn(deps.playwrightCliPath, args);
       if (result.exitCode !== 0) {
         throw new Error(formatError2(browser, result));
@@ -180912,6 +181256,7 @@ async function installBrowsers(ctx, pattern, deps) {
   await installBrowserList(ctx, browsers, {
     spawn: deps.spawn,
     platform: deps.platform,
+    browserDeps: deps.browserDeps,
     playwrightCliPath
   });
 }
@@ -180926,8 +181271,8 @@ async function collectBrowsers(files, peekFlowMeta) {
   }
   return [...seen].sort();
 }
-function buildArgs(browser, platform) {
-  return platform === "linux" ? ["install", "--with-deps", browser] : ["install", browser];
+function buildArgs(browser, platform, browserDeps) {
+  return platform === "linux" && browserDeps ? ["install", "--with-deps", browser] : ["install", browser];
 }
 function formatError2(browser, result) {
   if (result.exitCode < 0) {
@@ -180939,7 +181284,7 @@ function formatError2(browser, result) {
 }
 
 // src/domains/runner/runAndroidFlow.ts
-import path13 from "node:path";
+import path12 from "node:path";
 
 // src/shell/appium/createAndroidLaunchContext.ts
 import { writeFile } from "node:fs/promises";
@@ -181285,66 +181630,6 @@ function createRunner({
 }
 
 // src/domains/runner/runWebFlowUtils.ts
-import crypto from "node:crypto";
-import os6 from "node:os";
-import path12 from "node:path";
-function createLaunch({
-  browsers,
-  contextSetup,
-  launchBrowserOpts,
-  signals,
-  timeout,
-  traceMode = "off",
-  tracePath
-}) {
-  const openBrowsers = [];
-  const openContexts = [];
-  const tracingEnabled = traceMode !== "off";
-  let closed = false;
-  const closeAll = async () => {
-    if (closed)
-      return;
-    closed = true;
-    if (tracingEnabled && tracePath !== undefined) {
-      await Promise.allSettled(openContexts.map((c2) => c2.tracing.stop({ path: tracePath })));
-    }
-    await Promise.allSettled(openContexts.map((c2) => c2.close()));
-    await Promise.allSettled(openBrowsers.map((b4) => b4.close()));
-  };
-  const unregister = signals.register(closeAll);
-  const trackContext = async (ctx) => {
-    openContexts.push(ctx);
-    if (tracingEnabled) {
-      await ctx.tracing.start({ screenshots: true, snapshots: true });
-    }
-  };
-  const launch = async (launchOpts) => {
-    const browserName = normalizeBrowserName(launchOpts?.browser);
-    const bt2 = browsers[browserName];
-    if (launchOpts?.persistentContext === true) {
-      const userDataDir = launchOpts.userDataDir ?? path12.join(os6.tmpdir(), `qawolf-${crypto.randomUUID()}`);
-      const context2 = await bt2.launchPersistentContext(userDataDir, {
-        ...launchBrowserOpts,
-        ...contextSetup
-      });
-      context2.setDefaultTimeout(timeout);
-      await trackContext(context2);
-      const page = await context2.newPage();
-      return { browserType: browserName, context: context2, page };
-    }
-    const browser = await bt2.launch(launchBrowserOpts);
-    openBrowsers.push(browser);
-    const context = await browser.newContext(contextSetup);
-    context.setDefaultTimeout(timeout);
-    await trackContext(context);
-    return { browser, browserType: browserName, context };
-  };
-  const cleanup = async () => {
-    unregister();
-    await closeAll();
-  };
-  return { launch, cleanup };
-}
 function normalizeBrowserName(browser) {
   if (browser === "chrome" || browser === "msedge")
     return "chromium";
@@ -181384,7 +181669,7 @@ async function runAndroidFlow({
       throw new Error("runAndroidFlow: legacy flow functions are not supported; use flow() from @qawolf/flows/android");
     }
   } catch (err) {
-    const flowName2 = path13.basename(flowPath, path13.extname(flowPath));
+    const flowName2 = path12.basename(flowPath, path12.extname(flowPath));
     return {
       passed: false,
       testCounts: { passed: 0, total: 0 },
@@ -181452,13 +181737,13 @@ async function runAndroidFlow({
 }
 
 // src/domains/runner/runWebFlow.ts
-import path16 from "node:path";
+import path17 from "node:path";
 
 // src/domains/runner/initFlowRuntime.ts
-import path14 from "node:path";
+import path13 from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 async function runnerPathInDir(dir, fs9) {
-  const pkgPath = path14.join(dir, "node_modules", "@qawolf", "flows", "package.json");
+  const pkgPath = path13.join(dir, "node_modules", "@qawolf", "flows", "package.json");
   try {
     const pkg = JSON.parse(await fs9.readFile(pkgPath));
     const entry = pkg.exports?.["./_runner"];
@@ -181466,7 +181751,7 @@ async function runnerPathInDir(dir, fs9) {
     if (typeof importPath !== "string") {
       throw new Error(`@qawolf/flows at ${pkgPath} does not export "./_runner" with an "import" condition`);
     }
-    return path14.resolve(path14.dirname(pkgPath), importPath);
+    return path13.resolve(path13.dirname(pkgPath), importPath);
   } catch (err) {
     if (!isNoEntError(err))
       throw err;
@@ -181474,12 +181759,12 @@ async function runnerPathInDir(dir, fs9) {
   }
 }
 async function findFlowsRunnerPath(flowPath, fs9) {
-  let dir = path14.dirname(flowPath);
+  let dir = path13.dirname(flowPath);
   while (true) {
     const result = await runnerPathInDir(dir, fs9);
     if (result !== undefined)
       return result;
-    const parent2 = path14.dirname(dir);
+    const parent2 = path13.dirname(dir);
     if (parent2 === dir)
       throw new Error(`@qawolf/flows not found in node_modules above: ${flowPath}`);
     dir = parent2;
@@ -181511,7 +181796,7 @@ async function doInit(flowPath, timeout, fs9, depsRoot) {
   });
 }
 function initFlowRuntime(flowPath, options, fs9 = makeDefaultFs()) {
-  const startDir = path14.dirname(flowPath);
+  const startDir = path13.dirname(flowPath);
   let p3 = initCache.get(startDir);
   if (!p3) {
     p3 = doInit(flowPath, options.timeout, fs9, options.depsRoot);
@@ -181520,13 +181805,137 @@ function initFlowRuntime(flowPath, options, fs9 = makeDefaultFs()) {
   return p3;
 }
 
-// src/domains/runner/web/contextSetup.ts
+// src/domains/runner/createLaunch.ts
+import crypto from "node:crypto";
+import os6 from "node:os";
 import path15 from "node:path";
+
+// src/domains/runner/web/artifactPaths.ts
+import path14 from "node:path";
+function indexedArtifactPath(basePath, index2) {
+  if (index2 === 0)
+    return basePath;
+  const ext = path14.extname(basePath);
+  const base = path14.basename(basePath, ext);
+  return path14.join(path14.dirname(basePath), `${base}-${index2 + 1}${ext}`);
+}
+function createContextArtifacts(contextSetup, tracePath) {
+  let contextIndex = 0;
+  const harPaths = [];
+  const tracePaths = [];
+  const nextSetup = (overrides = {}) => {
+    const index2 = contextIndex;
+    contextIndex += 1;
+    const setup = { ...contextSetup, ...overrides };
+    if (contextSetup.recordHar !== undefined && overrides.recordHar === undefined) {
+      setup.recordHar = {
+        ...contextSetup.recordHar,
+        path: indexedArtifactPath(contextSetup.recordHar.path, index2)
+      };
+    }
+    if (setup.recordHar !== undefined)
+      harPaths.push(setup.recordHar.path);
+    return { setup, index: index2 };
+  };
+  const nextTracePath = (index2) => {
+    if (tracePath === undefined)
+      return;
+    const contextTracePath = indexedArtifactPath(tracePath, index2);
+    tracePaths.push(contextTracePath);
+    return contextTracePath;
+  };
+  const artifactPaths = () => ({
+    harPaths: [...harPaths],
+    tracePaths: [...tracePaths]
+  });
+  return { nextSetup, nextTracePath, artifactPaths };
+}
+
+// src/domains/runner/createLaunch.ts
+function createLaunch({
+  browsers,
+  contextSetup,
+  launchBrowserOpts,
+  signals,
+  timeout,
+  traceMode = "off",
+  tracePath
+}) {
+  const openBrowsers = [];
+  const openContexts = [];
+  const traceByContext = new Map;
+  const tracingEnabled = traceMode !== "off";
+  const { nextSetup, nextTracePath, artifactPaths } = createContextArtifacts(contextSetup, tracePath);
+  let closePromise;
+  const closeAll = () => {
+    closePromise ??= (async () => {
+      if (tracingEnabled) {
+        await Promise.allSettled(openContexts.map((c2) => {
+          const contextTracePath = traceByContext.get(c2);
+          return contextTracePath === undefined ? Promise.resolve() : c2.tracing.stop({ path: contextTracePath });
+        }));
+      }
+      await Promise.allSettled(openContexts.map((c2) => c2.close()));
+      await Promise.allSettled(openBrowsers.map((b4) => b4.close()));
+    })();
+    return closePromise;
+  };
+  const unregister = signals.register(closeAll);
+  const trackContext = async (ctx, index2) => {
+    openContexts.push(ctx);
+    if (tracingEnabled) {
+      const contextTracePath = nextTracePath(index2);
+      if (contextTracePath !== undefined) {
+        traceByContext.set(ctx, contextTracePath);
+      }
+      await ctx.tracing.start({ screenshots: true, snapshots: true });
+    }
+  };
+  const instrumentBrowser = (browser) => {
+    const originalNewContext = browser.newContext.bind(browser);
+    browser.newContext = async (opts) => {
+      const { setup, index: index2 } = nextSetup(opts);
+      const context = await originalNewContext(setup);
+      context.setDefaultTimeout(timeout);
+      await trackContext(context, index2);
+      return context;
+    };
+  };
+  const launch = async (launchOpts) => {
+    const browserName = normalizeBrowserName(launchOpts?.browser);
+    const bt2 = browsers[browserName];
+    if (launchOpts?.persistentContext === true) {
+      const userDataDir = launchOpts.userDataDir ?? path15.join(os6.tmpdir(), `qawolf-${crypto.randomUUID()}`);
+      const { setup, index: index2 } = nextSetup();
+      const context2 = await bt2.launchPersistentContext(userDataDir, {
+        ...launchBrowserOpts,
+        ...setup
+      });
+      context2.setDefaultTimeout(timeout);
+      await trackContext(context2, index2);
+      const page = await context2.newPage();
+      return { browserType: browserName, context: context2, page };
+    }
+    const browser = await bt2.launch(launchBrowserOpts);
+    openBrowsers.push(browser);
+    instrumentBrowser(browser);
+    const context = await browser.newContext({});
+    return { browser, browserType: browserName, context };
+  };
+  const cleanup = async () => {
+    unregister();
+    await closeAll();
+  };
+  return { launch, cleanup, artifactPaths };
+}
+
+// src/domains/runner/web/contextSetup.ts
+import path16 from "node:path";
 function harFlowPath(outputDir, flowName) {
-  return path15.join(outputDir, "har", `${flowName}.har`);
+  return path16.join(outputDir, "har", `${flowName}.har`);
 }
 function traceFlowPath(outputDir, flowName) {
-  return path15.join(outputDir, "trace", `${flowName}.zip`);
+  return path16.join(outputDir, "trace", `${flowName}.zip`);
 }
 function buildHarContextOpts(harPath, harContent) {
   return {
@@ -181542,7 +181951,7 @@ async function initHar(fs9, options, flowName) {
   if (harMode === "off")
     return { harMode, harPath: undefined };
   const harPath = harFlowPath(options.outputDir, flowName);
-  await fs9.mkdir(path15.dirname(harPath), { recursive: true });
+  await fs9.mkdir(path16.dirname(harPath), { recursive: true });
   return { harMode, harPath };
 }
 async function initTrace(fs9, options, flowName) {
@@ -181550,7 +181959,7 @@ async function initTrace(fs9, options, flowName) {
   if (traceMode === "off")
     return { traceMode, tracePath: undefined };
   const tracePath = traceFlowPath(options.outputDir, flowName);
-  await fs9.mkdir(path15.dirname(tracePath), { recursive: true });
+  await fs9.mkdir(path16.dirname(tracePath), { recursive: true });
   return { traceMode, tracePath };
 }
 async function maybeCleanupTrace(fs9, tracePath, passed, traceMode, warn) {
@@ -181563,7 +181972,7 @@ async function maybeCleanupTrace(fs9, tracePath, passed, traceMode, warn) {
   }
 }
 function buildContextSetup(videoSize, options, harPath) {
-  const videosDir = options.artifactDir ?? path15.join(options.outputDir, "videos");
+  const videosDir = options.artifactDir ?? path16.join(options.outputDir, "videos");
   const harOpts = harPath !== undefined ? buildHarContextOpts(harPath, options.harContent ?? "omit") : {};
   return options.video !== "off" ? {
     viewport: videoSize,
@@ -181599,7 +182008,7 @@ async function runWebFlow({
       depsRoot: deps.depsRoot
     });
   } catch (err) {
-    const flowName2 = path16.basename(flowPath, path16.extname(flowPath));
+    const flowName2 = path17.basename(flowPath, path17.extname(flowPath));
     return {
       passed: false,
       testCounts: { passed: 0, total: 0 },
@@ -181608,7 +182017,7 @@ async function runWebFlow({
     };
   }
   const isLegacy = typeof exported === "function";
-  const flowName = isLegacy ? path16.basename(flowPath, path16.extname(flowPath)) : exported.name;
+  const flowName = isLegacy ? path17.basename(flowPath, path17.extname(flowPath)) : exported.name;
   const runFn = isLegacy ? exported : exported.run;
   const { harMode, harPath } = await initHar(deps.fs, options, flowName);
   const { traceMode, tracePath } = await initTrace(deps.fs, options, flowName);
@@ -181619,7 +182028,7 @@ async function runWebFlow({
     slowMo: options.slowMo,
     ...options.executablePath !== undefined ? { executablePath: options.executablePath } : {}
   };
-  const { launch, cleanup } = createLaunch({
+  const { launch, cleanup, artifactPaths } = createLaunch({
     browsers: {
       chromium: deps.chromium,
       firefox: deps.firefox,
@@ -181661,25 +182070,26 @@ async function runWebFlow({
   } finally {
     await cleanup();
     const warn = (message) => deps.logger?.warn(message);
-    if (harPath !== undefined) {
-      await maybeCleanupHar(deps.fs, harPath, passed, harMode, warn);
+    const assigned = artifactPaths();
+    for (const contextHarPath of assigned.harPaths) {
+      await maybeCleanupHar(deps.fs, contextHarPath, passed, harMode, warn);
     }
-    if (tracePath !== undefined) {
-      await maybeCleanupTrace(deps.fs, tracePath, passed, traceMode, warn);
+    for (const contextTracePath of assigned.tracePaths) {
+      await maybeCleanupTrace(deps.fs, contextTracePath, passed, traceMode, warn);
     }
   }
 }
 
 // src/shell/embeddedWorkerCli.ts
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { basename as basename6, join as join32 } from "node:path";
+import { basename as basename6, join as join33 } from "node:path";
 var embeddedCliPathEnv = "QAWOLF_EMBEDDED_CLI_PATH";
 function extractEmbeddedWorkerCli() {
   const assetPath = process.env[embeddedCliPathEnv];
   if (assetPath === undefined || assetPath === "")
     return;
-  const dir = join32(getDataDir(), "worker");
-  const dest = join32(dir, basename6(assetPath));
+  const dir = join33(getDataDir(), "worker");
+  const dest = join33(dir, basename6(assetPath));
   if (existsSync3(dest))
     return dest;
   mkdirSync3(dir, { recursive: true });
@@ -181982,7 +182392,7 @@ function createCompositeReporter(reporters) {
   };
 }
 // src/shell/reporter/createJUnitReporter.ts
-import { join as join33 } from "node:path";
+import { join as join34 } from "node:path";
 
 // src/shell/reporter/junitXml.ts
 function escapeXml(str) {
@@ -182021,7 +182431,7 @@ ${suites}`;
 
 // src/shell/reporter/createJUnitReporter.ts
 function resolveJUnitOutputPath(junit, outputDir) {
-  return typeof junit === "string" && junit.trim() !== "" ? junit : join33(outputDir, "junit-report.xml");
+  return typeof junit === "string" && junit.trim() !== "" ? junit : join34(outputDir, "junit-report.xml");
 }
 function createJUnitReporter(deps) {
   const flows = [];
@@ -182084,6 +182494,7 @@ function buildFlowsRunDeps(args) {
     installBrowsers: (innerCtx, browsers) => installBrowserList(innerCtx, browsers, {
       spawn: defaultSpawn,
       platform: process.platform,
+      browserDeps: flags.browserDeps,
       playwrightCliPath: resolvePlaywrightCli(resolvedDir, process.platform)
     }),
     runWebFlow,
@@ -182108,11 +182519,11 @@ function buildFlowsRunDeps(args) {
 
 // src/commands/flows/loadEnvFile.ts
 import { readFile } from "node:fs/promises";
-import { join as join34 } from "node:path";
+import { join as join35 } from "node:path";
 async function loadEnvFile(envDir) {
   let content;
   try {
-    content = await readFile(join34(envDir, ".env"), "utf8");
+    content = await readFile(join35(envDir, ".env"), "utf8");
   } catch (err) {
     if (isNoEntError(err))
       return;
@@ -182212,7 +182623,7 @@ async function handleFlowsRun(ctx, pattern, flags, deps) {
 }
 
 // src/commands/flows/hybridRunDefaults.ts
-import { join as join35, resolve as resolve9 } from "node:path";
+import { join as join36, resolve as resolve9 } from "node:path";
 function makeDefaultHybridDeps(fs9) {
   return {
     expandPatterns: (patterns, cwd, logger) => expandPatterns(patterns, cwd, logger, fs9),
@@ -182231,7 +182642,7 @@ async function handleHybridFlowsRun(ctx, pattern, flags, deps) {
   if (validation !== "ok") {
     return { error: validation.error, exitCode: 2 };
   }
-  const envDir = resolve9(join35(".qawolf", flags.env));
+  const envDir = resolve9(join36(".qawolf", flags.env));
   const patternArgs = buildPatternArgs(pattern);
   const globFlows = () => resolvedDeps.expandPatterns(patternArgs, envDir, ctx.log("flows"));
   let files = await globFlows();
@@ -182268,7 +182679,7 @@ Examples:
 function registerFlowsRunCommand(flows, signals) {
   declareCommandKind(flows.command("run [pattern]"), "local", {
     kindNote: "read with --env"
-  }).description("Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment").option("--retries <n>", "Retry each failing flow up to this many times", parseInteger("--retries", { min: 0 }), 0).option("--bail", "Stop the run after the first failure", false).option("--workers <n>", "Parallel worker count for web flows", parseInteger("--workers", { min: 1 }), 1).option("--timeout <ms>", "Default timeout for actions and assertions, in milliseconds", parseInteger("--timeout", { min: 0 }), 30000).option("--video <mode>", "Record video: on | off | retain-on-failure", parseEnum("--video", videoModes), videoDefault).option("--trace <mode>", "Record Playwright trace: on | off | retain-on-failure", parseEnum("--trace", traceModes), traceDefault).option("--har <mode>", "Record HAR network log: on | off | retain-on-failure", parseEnum("--har", harModes), harDefault).option("--har-content <mode>", "HAR response bodies: omit | full (full uses more memory)", parseEnum("--har-content", harContentModes), harContentDefault).option("--output-dir <path>", "Directory for run artifacts (videos, traces, HAR)", defaultOutputDir).option("--junit [path]", "Write a JUnit XML report (default: <output-dir>/junit-report.xml)").option("--headed", "Show the browser window instead of headless", false).option("--env <env>", "Pull and run a flow from this environment (UUID or slug) if not cached locally").option("--deps <dir>", "Use this prepared dependency directory instead of auto-installing the runtime; or set QAWOLF_RUNTIME_DIR to relocate the managed runtime").addHelpText("after", runExamples).action((pattern, opts, command) => {
+  }).description("Run flows matching [pattern], or every flow when omitted; with --env, pull missing flows from that QA Wolf environment").option("--retries <n>", "Retry each failing flow up to this many times", parseInteger("--retries", { min: 0 }), 0).option("--bail", "Stop the run after the first failure", false).option("--workers <n>", "Parallel worker count for web flows", parseInteger("--workers", { min: 1 }), 1).option("--timeout <ms>", "Default timeout for actions and assertions, in milliseconds", parseInteger("--timeout", { min: 0 }), 30000).option("--video <mode>", "Record video: on | off | retain-on-failure", parseEnum("--video", videoModes), videoDefault).option("--trace <mode>", "Record Playwright trace: on | off | retain-on-failure", parseEnum("--trace", traceModes), traceDefault).option("--har <mode>", "Record HAR network log: on | off | retain-on-failure", parseEnum("--har", harModes), harDefault).option("--har-content <mode>", "HAR response bodies: omit | full (full uses more memory)", parseEnum("--har-content", harContentModes), harContentDefault).option("--output-dir <path>", "Directory for run artifacts (videos, traces, HAR)", defaultOutputDir).option("--junit [path]", "Write a JUnit XML report (default: <output-dir>/junit-report.xml)").option("--headed", "Show the browser window instead of headless", false).option("--env <env>", "Pull and run a flow from this environment (UUID or slug) if not cached locally").option("--deps <dir>", "Use this prepared dependency directory instead of auto-installing the runtime; or set QAWOLF_RUNTIME_DIR to relocate the managed runtime").option("--no-browser-deps", "Skip installing OS-level browser dependencies (Linux --with-deps, which needs root); requires the system libraries to already be present").addHelpText("after", runExamples).action((pattern, opts, command) => {
     if (opts.env !== undefined) {
       const hybridFlags = { ...opts, env: opts.env };
       return withAuthContext(signals, (ctx) => handleHybridFlowsRun(ctx, pattern, hybridFlags))(opts, command);
@@ -182305,7 +182716,7 @@ async function runWorker(signals) {
       throw new Error("worker subprocess currently supports web flows only");
     await configureTestkit(input.resolvedDir);
     const fs9 = makeDefaultFs();
-    const apiBaseUrl = process.env["QAWOLF_API_URL"]?.replace(/\/+$/, "") || "https://app.qawolf.com";
+    const apiBaseUrl = resolveHostUrl(process.env);
     const flowRuntimeDeps = await createFlowRuntimeDeps({
       envDir: input.resolvedDir,
       ctx: { apiBaseUrl, configDir: getConfigDir(), fs: fs9 }
@@ -182385,7 +182796,7 @@ function registerFlowsCommand(program2, signals) {
 }
 
 // src/domains/init/init.ts
-import { dirname as dirname13, join as join36, relative as relative7 } from "node:path";
+import { dirname as dirname13, join as join37, relative as relative7 } from "node:path";
 
 // src/domains/init/templates.ts
 var qawolfConfigTs = `export default {
@@ -182423,9 +182834,9 @@ function makeDefaultInitDeps() {
 async function handleInit(ctx, opts, deps = makeDefaultInitDeps()) {
   ctx.ui.gap();
   ctx.ui.intro(initMessages.title);
-  const configPath = join36(deps.cwd, "qawolf.config.ts");
-  const flowPath = join36(deps.cwd, "src", "flows", "example.flow.ts");
-  const gitignorePath = join36(deps.cwd, ".qawolf", ".gitignore");
+  const configPath = join37(deps.cwd, "qawolf.config.ts");
+  const flowPath = join37(deps.cwd, "src", "flows", "example.flow.ts");
+  const gitignorePath = join37(deps.cwd, ".qawolf", ".gitignore");
   await writeWithPrompt(ctx, configPath, qawolfConfigTs, opts.yes, deps);
   await writeWithPrompt(ctx, flowPath, exampleFlowTs, opts.yes, deps);
   await writeWithPrompt(ctx, gitignorePath, qawolfGitignore, opts.yes, deps);
@@ -182449,7 +182860,7 @@ async function writeWithPrompt(ctx, filePath, content, yes, deps) {
   ctx.ui.step(initMessages.createdFile(relPath));
 }
 async function ensurePackageJson(ctx, yes, deps) {
-  const pkgPath = join36(deps.cwd, "package.json");
+  const pkgPath = join37(deps.cwd, "package.json");
   if (!await deps.fs.pathExists(pkgPath)) {
     const confirmed2 = await ctx.ui.confirm(initMessages.createPackageJsonPrompt, { yes });
     if (!confirmed2.ok || !confirmed2.value) {
@@ -182508,19 +182919,19 @@ Examples:
 }
 
 // src/commands/install/android.ts
-import { join as join39 } from "node:path";
+import { join as join40 } from "node:path";
 
 // src/domains/install/android/index.ts
 import { parseExecutionTarget as parseExecutionTarget4 } from "@qawolf/flow-targets";
 
 // src/domains/install/android/avd.ts
-import { join as join37 } from "node:path";
+import { join as join38 } from "node:path";
 async function installAvds(ctx, specs, deps) {
   const versionResult = await deps.spawn(deps.sdkManagerPath, ["--version"]);
   if (versionResult.exitCode !== 0) {
     throw new Error(installMessages.android.sdkmanagerNotFound(deps.sdkManagerPath));
   }
-  const licenseFile = join37(deps.androidHome, "licenses", "android-sdk-license");
+  const licenseFile = join38(deps.androidHome, "licenses", "android-sdk-license");
   if (deps.checkExists(licenseFile)) {
     ctx.ui.info(installMessages.android.licensesAlreadyAccepted);
   } else {
@@ -182534,7 +182945,7 @@ async function installAvds(ctx, specs, deps) {
   for (const spec of specs) {
     if (installedImages.has(spec.systemImage))
       continue;
-    const systemImg = join37(deps.androidHome, ...spec.systemImage.split(";"), "system.img");
+    const systemImg = join38(deps.androidHome, ...spec.systemImage.split(";"), "system.img");
     if (deps.checkExists(systemImg)) {
       ctx.ui.info(installMessages.android.systemImageAlreadyInstalled(spec.systemImage));
       installedImages.add(spec.systemImage);
@@ -182582,9 +182993,9 @@ async function installAvds(ctx, specs, deps) {
 }
 
 // src/domains/install/android/driver.ts
-import { join as join38 } from "node:path";
+import { join as join39 } from "node:path";
 var appiumEnv = {
-  APPIUM_HOME: join38(envPaths("qawolf").data, "appium")
+  APPIUM_HOME: join39(envPaths("qawolf").data, "appium")
 };
 async function installUiautomator2Driver(ctx, deps) {
   const listResult = await deps.spawn(deps.appiumBinPath, ["driver", "list", "--installed"], { env: appiumEnv });
@@ -182671,8 +183082,8 @@ async function handleInstallAndroid(ctx, pattern, envDir) {
     arch: process.arch,
     androidHome: androidHome2,
     checkExists: (path9) => fs9.existsSync(path9),
-    sdkManagerPath: join39(androidHome2, "cmdline-tools", "latest", "bin", "sdkmanager"),
-    avdManagerPath: join39(androidHome2, "cmdline-tools", "latest", "bin", "avdmanager"),
+    sdkManagerPath: join40(androidHome2, "cmdline-tools", "latest", "bin", "sdkmanager"),
+    avdManagerPath: join40(androidHome2, "cmdline-tools", "latest", "bin", "avdmanager"),
     expandPatterns: (patterns, cwd) => expandPatterns(patterns, cwd ?? process.cwd(), undefined, fs9),
     peekFlowMeta: makePeekFlowMeta(fs9),
     resolveDepsRoot: async (files) => envDir ?? (await resolveDepsRoot({ files, fs: fs9 })).depsRoot,
@@ -182681,13 +183092,15 @@ async function handleInstallAndroid(ctx, pattern, envDir) {
 }
 
 // src/commands/install/browsers.ts
-async function handleInstallBrowsers(ctx, pattern, envDir) {
+async function handleInstallBrowsers(ctx, pattern, options) {
   const cwd = process.cwd();
   const { fs: fs9 } = ctx;
+  const { envDir, browserDeps } = options;
   return installBrowsers(ctx, pattern, {
     cwd,
     spawn: defaultSpawn,
     platform: process.platform,
+    browserDeps,
     expandPatterns: (patterns, dir) => expandPatterns(patterns, dir ?? cwd, undefined, fs9),
     peekFlowMeta: makePeekFlowMeta(fs9),
     resolvePlaywrightCliPath: async (files) => {
@@ -182752,18 +183165,27 @@ async function installAll(ctx, pattern, deps) {
   }
   return firstError;
 }
-async function handleInstall(ctx, pattern) {
+async function handleInstall(ctx, pattern, options) {
   const { fs: fs9 } = ctx;
   return installAll(ctx, pattern, {
     cwd: process.cwd(),
     expandPatterns: (patterns, cwd) => expandPatterns(patterns, cwd ?? process.cwd(), undefined, fs9),
     peekFlowMeta: makePeekFlowMeta(fs9),
     resolveDepsRoot: (files) => resolveDepsRoot({ files, fs: fs9 }),
-    installBrowsers: handleInstallBrowsers,
+    installBrowsers: (innerCtx, innerPattern, envDir) => handleInstallBrowsers(innerCtx, innerPattern, {
+      envDir,
+      browserDeps: options.browserDeps
+    }),
     installAndroid: handleInstallAndroid
   });
 }
 
+// src/commands/install/browserDepsFlag.ts
+function mergedBrowserDeps(local, command) {
+  const parent2 = command.parent?.opts().browserDeps;
+  return local && parent2 !== false;
+}
+
 // src/commands/install/clear.ts
 async function handleInstallClear(ctx, opts) {
   const dir = managedEnvBaseDir();
@@ -182791,18 +183213,22 @@ async function handleInstallClear(ctx, opts) {
 }
 
 // src/commands/install/index.ts
+var noBrowserDepsDescription = "Skip installing OS-level browser dependencies (Linux --with-deps, which needs root); requires the system libraries to already be present";
 function registerInstallCommand(program2, signals) {
-  const install = declareCommandKind(program2.command("install"), "local").description("Install every runtime dependency the project's flows need").argument("[pattern]", "Glob limiting which flows determine required dependencies").addHelpText("after", `
+  const install = declareCommandKind(program2.command("install"), "local").description("Install every runtime dependency the project's flows need").argument("[pattern]", "Glob limiting which flows determine required dependencies").option("--no-browser-deps", noBrowserDepsDescription).addHelpText("after", `
 Examples:
   $ qawolf install
   $ qawolf install "flows/checkout/**"`).action((pattern, opts, command) => {
-    return withContext(signals, (ctx) => handleInstall(ctx, pattern))(opts, command);
+    return withContext(signals, (ctx) => handleInstall(ctx, pattern, { browserDeps: opts.browserDeps }))(opts, command);
   });
-  declareCommandKind(install.command("browsers [pattern]"), "local").description("Install Playwright browsers used by the project's web flows").addHelpText("after", `
+  declareCommandKind(install.command("browsers [pattern]"), "local").description("Install Playwright browsers used by the project's web flows").option("--no-browser-deps", noBrowserDepsDescription).addHelpText("after", `
 Examples:
   $ qawolf install browsers
   $ qawolf install browsers "flows/web/**"`).action((pattern, opts, command) => {
-    return withContext(signals, (ctx) => handleInstallBrowsers(ctx, pattern))(opts, command);
+    return withContext(signals, (ctx) => handleInstallBrowsers(ctx, pattern, {
+      envDir: undefined,
+      browserDeps: mergedBrowserDeps(opts.browserDeps, command)
+    }))(opts, command);
   });
   declareCommandKind(install.command("android [pattern]"), "local").description("Install Android system images, AVDs, and the Appium driver used by the project's Android flows").addHelpText("after", `
 Examples:
@@ -182818,8 +183244,7 @@ Examples:
   });
 }
 
-// src/core/publicApi/flagSpecs.ts
-var kebabCase = (field) => field.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+// src/core/publicApi/flagKind.ts
 function flagKind(schema) {
   if (schema.type === "string")
     return { ok: true, kind: "string" };
@@ -182854,6 +183279,110 @@ function flagKind(schema) {
     reason: `type ${schema.type ?? "unknown"} cannot be expressed as a flag`
   };
 }
+
+// src/core/publicApi/objectShape.ts
+var asObjectShape = (schema) => schema.type === "object" && schema.properties ? { properties: schema.properties, required: new Set(schema.required) } : undefined;
+function mergeIntersection(members) {
+  const shape = { properties: {}, required: new Set };
+  for (const member of members) {
+    const memberShape = asObjectShape(member);
+    if (!memberShape) {
+      return {
+        ok: false,
+        field: "",
+        reason: "intersection members must be object schemas"
+      };
+    }
+    for (const [field, fieldSchema] of Object.entries(memberShape.properties)) {
+      if (field in shape.properties) {
+        return {
+          ok: false,
+          field,
+          reason: "field appears in multiple intersection members"
+        };
+      }
+      shape.properties[field] = fieldSchema;
+      if (memberShape.required.has(field))
+        shape.required.add(field);
+    }
+  }
+  return { ok: true, shape };
+}
+function mergeUnion(branches) {
+  const shapes = [];
+  for (const branch of branches) {
+    const branchShape = asObjectShape(branch);
+    if (!branchShape) {
+      return {
+        ok: false,
+        field: "",
+        reason: "union branches must be object schemas"
+      };
+    }
+    shapes.push(branchShape);
+  }
+  const shape = { properties: {}, required: new Set };
+  for (const branchShape of shapes) {
+    for (const [field, fieldSchema] of Object.entries(branchShape.properties)) {
+      const existing = shape.properties[field];
+      if (!existing) {
+        shape.properties[field] = { ...fieldSchema };
+        continue;
+      }
+      const kinds2 = [flagKind(existing), flagKind(fieldSchema)];
+      if (kinds2[0]?.ok && kinds2[1]?.ok && kinds2[0].kind !== kinds2[1].kind) {
+        return {
+          ok: false,
+          field,
+          reason: "field has conflicting types across union branches"
+        };
+      }
+      if (!existing.description && fieldSchema.description) {
+        existing.description = fieldSchema.description;
+      }
+    }
+  }
+  const discriminator = Object.keys(shape.properties).find((field) => {
+    const values = shapes.map((branch) => branch.properties[field]?.const);
+    return values.every((value) => typeof value === "string") && new Set(values).size === shapes.length && shapes.every((branch) => branch.required.has(field));
+  });
+  if (discriminator === undefined) {
+    return {
+      ok: false,
+      field: "",
+      reason: "union branches must share a literal discriminator field"
+    };
+  }
+  for (const [field, fieldSchema] of Object.entries(shape.properties)) {
+    const occurrences = shapes.filter((branch) => (field in branch.properties));
+    if (occurrences.length === shapes.length && occurrences.every((branch) => branch.required.has(field))) {
+      shape.required.add(field);
+    }
+    if (field === discriminator) {
+      const values = shapes.map((branch) => branch.properties[field]?.const);
+      fieldSchema.description = `One of: ${values.join(", ")}`;
+    }
+  }
+  return { ok: true, shape };
+}
+function toObjectShape(schema) {
+  if (schema.allOf)
+    return mergeIntersection(schema.allOf);
+  const branches = schema.oneOf ?? schema.anyOf;
+  if (branches)
+    return mergeUnion(branches);
+  const shape = asObjectShape(schema);
+  if (shape)
+    return { ok: true, shape };
+  return {
+    ok: false,
+    field: "",
+    reason: "contract input must be an object schema"
+  };
+}
+
+// src/core/publicApi/flagSpecs.ts
+var kebabCase = (field) => field.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 function flagUsage(field, kind) {
   const name = `--${kebabCase(field)}`;
   if (kind === "boolean")
@@ -182868,16 +183397,11 @@ function buildFlagSpecs(inputSchema) {
   const jsonSchema = exports_external.toJSONSchema(inputSchema, {
     io: "input"
   });
-  if (jsonSchema.type !== "object" || !jsonSchema.properties) {
-    return {
-      ok: false,
-      field: "",
-      reason: "contract input must be an object schema"
-    };
-  }
-  const required2 = new Set(jsonSchema.required ?? []);
+  const result = toObjectShape(jsonSchema);
+  if (!result.ok)
+    return result;
   const flags = [];
-  for (const [field, fieldSchema] of Object.entries(jsonSchema.properties)) {
+  for (const [field, fieldSchema] of Object.entries(result.shape.properties)) {
     const kind = flagKind(fieldSchema);
     if (!kind.ok)
       return { ok: false, field, reason: kind.reason };
@@ -182885,7 +183409,7 @@ function buildFlagSpecs(inputSchema) {
       field,
       flag: flagUsage(field, kind.kind),
       description: fieldSchema.description ?? "",
-      required: required2.has(field),
+      required: result.shape.required.has(field),
       kind: kind.kind
     });
   }
@@ -183063,4 +183587,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=64AB4032821CC8E864756E2164756E21
+//# debugId=F2AE77060354D60864756E2164756E21