@qawolf/cli 1.10.0 → 1.11.2

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 join35(s3) {
+    BufferList.prototype.join = function join36(s3) {
       if (this.length === 0)
         return "";
       var p3 = this.head;
@@ -23182,7 +23182,7 @@ var require_BufferList2 = __commonJS((exports, module) => {
       this.head = this.tail = null;
       this.length = 0;
     };
-    BufferList.prototype.join = function join35(s3) {
+    BufferList.prototype.join = function join36(s3) {
       if (this.length === 0)
         return "";
       var p3 = this.head;
@@ -134457,7 +134457,7 @@ var require_snapshot_utils = __commonJS((exports, module) => {
 // node_modules/undici/lib/mock/snapshot-recorder.js
 var require_snapshot_recorder = __commonJS((exports, module) => {
   var { writeFile, readFile, mkdir } = __require("node:fs/promises");
-  var { dirname: dirname11, resolve: resolve10 } = __require("node:path");
+  var { dirname: dirname12, resolve: resolve10 } = __require("node:path");
   var { setTimeout: setTimeout3, clearTimeout: clearTimeout2 } = __require("node:timers");
   var { InvalidArgumentError: InvalidArgumentError3, UndiciError } = require_errors7();
   var { hashId, isUrlExcludedFactory, normalizeHeaders, createHeaderFilters } = require_snapshot_utils();
@@ -134652,7 +134652,7 @@ var require_snapshot_recorder = __commonJS((exports, module) => {
         throw new InvalidArgumentError3("Snapshot path is required");
       }
       const resolvedPath = resolve10(path4);
-      await mkdir(dirname11(resolvedPath), { recursive: true });
+      await mkdir(dirname12(resolvedPath), { recursive: true });
       const data2 = Array.from(this.#snapshots.entries()).map(([hash2, snapshot]) => ({
         hash: hash2,
         snapshot
@@ -156448,6 +156448,12 @@ var interactiveRunnerMessages = {
   targetMismatch: (runnerName, requiredRunnerName) => `This flow needs a ${requiredRunnerName} runner and ${runnerName} is running. Launch one with --name ${requiredRunnerName}.`
 };
 // src/core/messages/runner.ts
+var maxListedNames = 5;
+function listNames(names) {
+  const shown = names.slice(0, maxListedNames).join(", ");
+  const rest = names.length - maxListedNames;
+  return rest > 0 ? `${shown} and ${rest} more` : shown;
+}
 var runnerMessages = {
   playwrightLoadFailed: (envDir, detail) => packageLoadFailed("Playwright", envDir, detail),
   androidWorkersUnsupported: "Android flows are not yet supported with --workers > 1; rerun Android flows with --workers 1.",
@@ -156477,6 +156483,12 @@ ${dir}`,
   ].join(`
 `),
   outerHopCandidateRejected: (dir, missing) => `outer-hop candidate rejected: ${dir} missing ${missing.join(", ")}`,
+  outerHopFallbackNotice: (dir, missing) => [
+    `Not reusing ${dir} — it is missing ${listNames(missing)}.`,
+    `Installing the declared dependencies instead. Run 'npm install' there to reuse it.`
+  ].join(`
+`),
+  outerHopCarriedOver: (names) => `Carried over ${pluralize(names.length, "undeclared package")} from the project node_modules: ${listNames(names)}. Declare them in package.json "dependencies".`,
   moduleNotFoundHint: (pkg, projectDir) => projectDir === undefined ? `Hint: '${pkg}' could not be resolved. Run from within your flows project so its dependencies can be found.` : `Hint: '${pkg}' could not be resolved. Ensure it is declared in ${projectDir}/package.json "dependencies" and run npm install in that project.`
 };
 // src/core/messages/updateCheck.ts
@@ -175911,7 +175923,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.10.0",
+  version: "1.11.2",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -175979,7 +175991,6 @@ var package_default = {
     appium: "2.11.3",
     commander: "14.0.3",
     "env-paths": "4.0.0",
-    "expect-webdriverio": "5.6.5",
     picomatch: "4.0.4",
     pino: "10.3.1",
     playwright: "1.62.0",
@@ -175996,6 +176007,7 @@ var package_default = {
     "@types/bun": "1.3.14",
     "@types/picomatch": "4.0.3",
     "appium-uiautomator2-driver": "4.2.9",
+    "expect-webdriverio": "5.6.5",
     knip: "6.16.1",
     oxfmt: "0.54.0",
     oxlint: "1.69.0",
@@ -177789,7 +177801,8 @@ async function expandPatterns(patterns, cwd, logger, fs3) {
   for (const root of roots) {
     const matches = await glob(effectivePatterns, {
       cwd: root,
-      absolute: true
+      absolute: true,
+      ignore: ["**/node_modules/**"]
     });
     for (const match of matches) {
       const file2 = resolve3(match);
@@ -182468,6 +182481,14 @@ function buildPatternArgs(pattern) {
   return pattern ? [pattern] : [];
 }
 
+// src/core/flowFailureHint.ts
+function flowFailureHint(errText, projectDir) {
+  const missingPackage = extractMissingPackage(errText);
+  if (missingPackage === undefined)
+    return;
+  return runnerMessages.moduleNotFoundHint(missingPackage, projectDir);
+}
+
 // src/shell/reporter/createCompositeReporter.ts
 function callEach(reporters, pick2, event) {
   for (const r2 of reporters) {
@@ -182534,6 +182555,26 @@ function formatErrorWithCause(err) {
 `);
 }
 
+// src/domains/runner/jsonFailureDetails.ts
+function collectJsonFailureDetails(reporter, projectDir) {
+  const details = [];
+  return {
+    reporter: createCompositeReporter([
+      reporter,
+      {
+        onFlowFail: ({ err }) => {
+          const detail = formatErrorWithCause(err);
+          const hint = flowFailureHint(detail, projectDir);
+          details.push(hint === undefined ? detail : `${detail}
+
+${hint}`);
+        }
+      }
+    ]),
+    details
+  };
+}
+
 // src/domains/runner/runAndroidFlowUtils.ts
 import { parseExecutionTarget as parseExecutionTarget3 } from "@qawolf/flow-targets";
 
@@ -182589,7 +182630,7 @@ class FlowRunError extends Error {
   }
 }
 
-// src/domains/runner/runInternals.ts
+// src/domains/runner/dispatchFlow.ts
 async function dispatchFlow({
   deps,
   flow,
@@ -182881,13 +182922,9 @@ async function flowsRun(ctx, files, flags, deps) {
     return { error: runnerMessages.androidWorkersUnsupported, exitCode: 2 };
   }
   const { webOptions, androidOptions } = buildRunOptions(flags);
-  const failureDetails = [];
-  const reporter = ctx.outputMode === "json" ? createCompositeReporter([
-    deps.reporter,
-    {
-      onFlowFail: ({ err }) => failureDetails.push(formatErrorWithCause(err))
-    }
-  ]) : deps.reporter;
+  const collected = ctx.outputMode === "json" ? collectJsonFailureDetails(deps.reporter, deps.projectDir) : undefined;
+  const failureDetails = collected?.details ?? [];
+  const reporter = collected?.reporter ?? deps.reporter;
   const result = await executeFlows({
     ctx,
     deps: { ...deps, reporter },
@@ -182975,7 +183012,7 @@ async function defaultRunWebFlowDeps(envDir = process.cwd(), signals) {
 
 // src/domains/runtimeEnv/prepareRunDir.ts
 import { createHash as createHash4 } from "node:crypto";
-import { join as join32, resolve as resolve9 } from "node:path";
+import { join as join33, resolve as resolve9 } from "node:path";
 
 // src/domains/runtimeEnv/execSubpathImports.ts
 import { join as join26 } from "node:path";
@@ -183044,9 +183081,82 @@ async function populateInnerHop(args) {
 }
 
 // src/domains/runtimeEnv/outerHop.ts
+import { lstat as lstat2 } from "node:fs/promises";
+import { dirname as dirname10, join as join30 } from "node:path";
+
+// src/domains/runtimeEnv/carryOverPackages.ts
 import { lstat } from "node:fs/promises";
 import { dirname as dirname9, join as join29 } from "node:path";
+
+// src/domains/runtimeEnv/carryOverPlan.ts
 var executorPackageNames = new Set(pinnedPackages.map((p3) => p3.name));
+function planCarryOver(args) {
+  const installed = new Set(args.installed);
+  return args.present.filter((name) => !name.startsWith(".") && !installed.has(name) && !executorPackageNames.has(name));
+}
+
+// src/domains/runtimeEnv/carryOverPackages.ts
+async function carryOverPackages(args) {
+  const { projectModulesDir, nodeModulesDir, fs: fs4 } = args;
+  const present = await listPackageNames(projectModulesDir, fs4);
+  if (present.length === 0)
+    return [];
+  const names = planCarryOver({
+    present,
+    installed: await listPackageNames(nodeModulesDir, fs4)
+  });
+  const linked = [];
+  for (const name of names) {
+    const segments = name.split("/");
+    const target = join29(nodeModulesDir, ...segments);
+    if (await pathOccupied(target))
+      continue;
+    if (segments.length > 1)
+      await fs4.mkdir(dirname9(target), { recursive: true });
+    await createDirSymlink(join29(projectModulesDir, ...segments), target);
+    linked.push(name);
+  }
+  return linked;
+}
+async function pathOccupied(path3) {
+  try {
+    await lstat(path3);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function listPackageNames(dir, fs4) {
+  let entries;
+  try {
+    entries = await fs4.readdir(dir);
+  } catch {
+    return [];
+  }
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.startsWith("@")) {
+      if (fs4.existsSync(join29(dir, entry, "package.json")))
+        names.push(entry);
+      continue;
+    }
+    let scoped;
+    try {
+      scoped = await fs4.readdir(join29(dir, entry));
+    } catch {
+      continue;
+    }
+    for (const inner of scoped) {
+      if (fs4.existsSync(join29(dir, entry, inner, "package.json"))) {
+        names.push(`${entry}/${inner}`);
+      }
+    }
+  }
+  return names;
+}
+
+// src/domains/runtimeEnv/outerHop.ts
+var executorPackageNames2 = new Set(pinnedPackages.map((p3) => p3.name));
 async function populateOuterHop(args) {
   const { projectDir, runDir, fs: fs4 } = args;
   if (projectDir === undefined)
@@ -183055,7 +183165,7 @@ async function populateOuterHop(args) {
   const depNames = Object.keys(installableDeps);
   const { satisfying, rejected } = await findSatisfyingNodeModulesDir(projectDir, depNames, fs4);
   if (satisfying !== undefined) {
-    await createDirSymlink(satisfying, join29(runDir, "node_modules"));
+    await createDirSymlink(satisfying, join30(runDir, "node_modules"));
     return { mode: "symlink", nodeModulesDir: satisfying };
   }
   if (depNames.length === 0)
@@ -183064,24 +183174,29 @@ async function populateOuterHop(args) {
   await installOuterDeps(runDir, installableDeps, fs4, args.install ?? spawnNpmInstall);
   await linkPinnedPackages({
     depsRoot: args.depsRoot,
-    nodeModulesDir: join29(runDir, "node_modules"),
+    nodeModulesDir: join30(runDir, "node_modules"),
     fs: fs4
   });
-  return { mode: "install", depCount: depNames.length, rejected };
+  const carriedOver = await carryOverPackages({
+    projectModulesDir: join30(projectDir, "node_modules"),
+    nodeModulesDir: join30(runDir, "node_modules"),
+    fs: fs4
+  });
+  return { mode: "install", depCount: depNames.length, rejected, carriedOver };
 }
 async function findSatisfyingNodeModulesDir(startDir, depNames, fs4) {
   const rejected = [];
   let dir = startDir;
   while (true) {
-    const candidate = join29(dir, "node_modules");
+    const candidate = join30(dir, "node_modules");
     const stats = await lstatSafe(candidate);
     if (stats !== undefined && stats.isDirectory() && !stats.isSymbolicLink()) {
-      const missing = depNames.filter((name) => !fs4.existsSync(join29(candidate, name, "package.json")));
+      const missing = depNames.filter((name) => !fs4.existsSync(join30(candidate, name, "package.json")));
       if (missing.length === 0)
         return { satisfying: candidate, rejected };
       rejected.push({ dir: candidate, missing });
     }
-    const parent = dirname9(dir);
+    const parent = dirname10(dir);
     if (parent === dir)
       return { satisfying: undefined, rejected };
     dir = parent;
@@ -183089,7 +183204,7 @@ async function findSatisfyingNodeModulesDir(startDir, depNames, fs4) {
 }
 async function lstatSafe(path3) {
   try {
-    return await lstat(path3);
+    return await lstat2(path3);
   } catch {
     return;
   }
@@ -183097,7 +183212,7 @@ async function lstatSafe(path3) {
 async function readInstallableDeps(projectDir, fs4) {
   let content;
   try {
-    content = await fs4.readFile(join29(projectDir, "package.json"));
+    content = await fs4.readFile(join30(projectDir, "package.json"));
   } catch {
     return {};
   }
@@ -183112,11 +183227,11 @@ async function readInstallableDeps(projectDir, fs4) {
   const rawDeps = parsed["dependencies"];
   if (typeof rawDeps !== "object" || rawDeps === null)
     return {};
-  return Object.fromEntries(Object.entries(rawDeps).filter(([name]) => !executorPackageNames.has(name)).filter((entry) => typeof entry[1] === "string"));
+  return Object.fromEntries(Object.entries(rawDeps).filter(([name]) => !executorPackageNames2.has(name)).filter((entry) => typeof entry[1] === "string"));
 }
 async function installOuterDeps(runDir, deps, fs4, install) {
-  await fs4.writeFile(join29(runDir, "package.json"), JSON.stringify({ name: "qawolf-run", private: true, dependencies: deps }, undefined, 2));
-  await fs4.writeFile(join29(runDir, ".npmrc"), `@qawolf:registry=https://registry.npmjs.org/
+  await fs4.writeFile(join30(runDir, "package.json"), JSON.stringify({ name: "qawolf-run", private: true, dependencies: deps }, undefined, 2));
+  await fs4.writeFile(join30(runDir, ".npmrc"), `@qawolf:registry=https://registry.npmjs.org/
 `);
   const result = await install(runDir);
   if (result.exitCode !== 0) {
@@ -183126,14 +183241,14 @@ async function installOuterDeps(runDir, deps, fs4, install) {
 
 // src/domains/runtimeEnv/stageFlowFiles.ts
 import { createHash as createHash3 } from "node:crypto";
-import { basename as basename4, dirname as dirname10, join as join31, sep as sep4 } from "node:path";
+import { basename as basename4, dirname as dirname11, join as join32, sep as sep4 } from "node:path";
 
 // src/shell/copyDir.ts
 import { cp, readdir as readdir2 } from "node:fs/promises";
-import { basename as basename3, join as join30 } from "node:path";
+import { basename as basename3, join as join31 } from "node:path";
 async function copyDirExcluding(source, destination, excludedNames) {
   const entries = await readdir2(source, { withFileTypes: true });
-  await Promise.all(entries.filter((entry) => !excludedNames.has(entry.name)).map((entry) => cp(join30(source, entry.name), join30(destination, entry.name), {
+  await Promise.all(entries.filter((entry) => !excludedNames.has(entry.name)).map((entry) => cp(join31(source, entry.name), join31(destination, entry.name), {
     recursive: true,
     filter: (path3) => !excludedNames.has(basename3(path3))
   })));
@@ -183150,14 +183265,14 @@ async function stageFlowFiles(args) {
   if (files.length > 1) {
     return Promise.all(files.map((f3) => stageOneFile(f3, execDir, fs4)));
   }
-  await Promise.all(files.map((f3) => fs4.copyFile(f3, join31(execDir, basename4(f3)))));
-  return files.map((f3) => join31(execDir, basename4(f3)));
+  await Promise.all(files.map((f3) => fs4.copyFile(f3, join32(execDir, basename4(f3)))));
+  return files.map((f3) => join32(execDir, basename4(f3)));
 }
 async function stageOneFile(file2, execDir, fs4) {
-  const dirHash = createHash3("sha256").update(dirname10(file2)).digest("hex").slice(0, 8);
-  const subDir = join31(execDir, dirHash);
+  const dirHash = createHash3("sha256").update(dirname11(file2)).digest("hex").slice(0, 8);
+  const subDir = join32(execDir, dirHash);
   await fs4.mkdir(subDir, { recursive: true });
-  const dest = join31(subDir, basename4(file2));
+  const dest = join32(subDir, basename4(file2));
   await fs4.copyFile(file2, dest);
   return dest;
 }
@@ -183165,7 +183280,7 @@ function remapPath(file2, projectDir, execDir) {
   if (file2 === projectDir)
     return execDir;
   if (file2.startsWith(projectDir + sep4)) {
-    return join31(execDir, file2.slice(projectDir.length + 1));
+    return join32(execDir, file2.slice(projectDir.length + 1));
   }
   return;
 }
@@ -183175,10 +183290,10 @@ async function prepareRunDir(args) {
   const { files, projectDir, depsRoot, runRoot } = args;
   const fs4 = args.fs ?? makeDefaultFs();
   const runId = buildRunId(projectDir, files);
-  const runDir = join32(runRoot, runId);
+  const runDir = join33(runRoot, runId);
   await fs4.rm(runDir, { recursive: true, force: true });
   await fs4.mkdir(runDir, { recursive: true });
-  const execDir = join32(runDir, "exec");
+  const execDir = join33(runDir, "exec");
   await fs4.mkdir(execDir, { recursive: true });
   await populateInnerHop({ depsRoot, execDir, fs: fs4 });
   const stagedFiles = await stageFlowFiles({ files, projectDir, execDir, fs: fs4 });
@@ -183209,17 +183324,17 @@ function buildRunId(projectDir, files) {
 }
 
 // src/shell/testkit.ts
-import { join as join33 } from "node:path";
+import { join as join34 } from "node:path";
 function notAvailableLocally(name) {
   throw new Error(runnerMessages.notAvailableLocally(name));
 }
 async function loadSdkDeps(cwd) {
-  const testkitDir = join33(cwd, "node_modules", "@qawolf", "testkit");
+  const testkitDir = join34(cwd, "node_modules", "@qawolf", "testkit");
   try {
     const clientMod = await importFromPath(resolveFromEnvDir(cwd, "@qawolf/testkit/client"));
     if (typeof clientMod.createTestkitClient !== "function")
       throw new Error("createTestkitClient is not a function");
-    const scopeMod = await importFromPath(join33(testkitDir, "dist", "clientScope.js"));
+    const scopeMod = await importFromPath(join34(testkitDir, "dist", "clientScope.js"));
     if (typeof scopeMod.configureTestkitClient !== "function")
       throw new Error("configureTestkitClient is not a function");
     return {
@@ -183277,9 +183392,9 @@ async function registerLazyEmailsClient(getInbox, cwd, deps) {
 }
 
 // src/commands/flows/envVarDeps.ts
-import { join as join34 } from "node:path";
+import { join as join35 } from "node:path";
 function envFilePath(envDir) {
-  return join34(envDir, ".env");
+  return join35(envDir, ".env");
 }
 async function readEnv(envDir, fs4) {
   try {
@@ -183383,6 +183498,9 @@ async function createFlowRuntimeDeps({
   };
 }
 
+// src/commands/flows/runStagedFlows.ts
+import { join as join39 } from "node:path";
+
 // src/shell/appium/createAppiumServer.ts
 import { existsSync as existsSync2 } from "node:fs";
 
@@ -183746,12 +183864,12 @@ Install Android Studio and open Tools > SDK Manager.`);
 }
 
 // src/shell/manifest/lookup.ts
-import { basename as basename5, dirname as dirname11, relative as relative6 } from "node:path";
+import { basename as basename5, dirname as dirname12, relative as relative6 } from "node:path";
 async function findFlowStamp(flowAbsPath) {
   let envDir;
-  let current = dirname11(flowAbsPath);
-  while (current !== dirname11(current)) {
-    const parent2 = dirname11(current);
+  let current = dirname12(flowAbsPath);
+  while (current !== dirname12(current)) {
+    const parent2 = dirname12(current);
     if (basename5(parent2) === ".qawolf") {
       envDir = current;
       break;
@@ -184683,14 +184801,14 @@ async function runWebFlow({
 
 // 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 join35 } from "node:path";
+import { basename as basename6, join as join36 } from "node:path";
 var embeddedCliPathEnv = "QAWOLF_EMBEDDED_CLI_PATH";
 function extractEmbeddedWorkerCli() {
   const assetPath = process.env[embeddedCliPathEnv];
   if (assetPath === undefined || assetPath === "")
     return;
-  const dir = join35(getDataDir(), "worker");
-  const dest = join35(dir, basename6(assetPath));
+  const dir = join36(getDataDir(), "worker");
+  const dest = join36(dir, basename6(assetPath));
   if (existsSync3(dest))
     return dest;
   mkdirSync3(dir, { recursive: true });
@@ -184845,7 +184963,7 @@ function makePooledDispatch(resolvedDir) {
 }
 
 // src/commands/flows/buildRunReporter.ts
-import { dirname as dirname12 } from "node:path";
+import { dirname as dirname13 } from "node:path";
 
 // src/shell/reporter/createConsoleReporter.ts
 import { styleText as styleText3 } from "node:util";
@@ -184892,9 +185010,9 @@ function createConsoleReporter(deps) {
       deps.stderr.write(`${formatted}
 
 `);
-      const missingPackage = extractMissingPackage(errStr);
-      if (missingPackage !== undefined) {
-        deps.stderr.write(`${styleText3("yellow", `${indent}${runnerMessages.moduleNotFoundHint(missingPackage, deps.projectDir)}`)}
+      const hint = flowFailureHint(errStr, deps.projectDir);
+      if (hint !== undefined) {
+        deps.stderr.write(`${styleText3("yellow", `${indent}${hint}`)}
 
 `);
       }
@@ -184928,7 +185046,7 @@ ${styleText3("dim", "─".repeat(width))}
   };
 }
 // src/shell/reporter/createJUnitReporter.ts
-import { join as join36 } from "node:path";
+import { join as join37 } from "node:path";
 
 // src/shell/reporter/junitXml.ts
 function escapeXml(str) {
@@ -184967,7 +185085,7 @@ ${suites}`;
 
 // src/shell/reporter/createJUnitReporter.ts
 function resolveJUnitOutputPath(junit, outputDir) {
-  return typeof junit === "string" && junit.trim() !== "" ? junit : join36(outputDir, "junit-report.xml");
+  return typeof junit === "string" && junit.trim() !== "" ? junit : join37(outputDir, "junit-report.xml");
 }
 function createJUnitReporter(deps) {
   const flows = [];
@@ -185006,7 +185124,7 @@ function buildRunReporter(flags, deps) {
   const junit = createJUnitReporter({
     outputPath: resolveJUnitOutputPath(flags.junit, flags.outputDir),
     writeFile: (path9, content) => {
-      deps.fs.mkdirSync(dirname12(path9), { recursive: true });
+      deps.fs.mkdirSync(dirname13(path9), { recursive: true });
       deps.fs.writeFileSync(path9, content);
     },
     stderr
@@ -185045,6 +185163,7 @@ function buildFlowsRunDeps(args) {
     findFlowStamp,
     warn: (message) => ctx.ui.warn(message),
     logger: ctx.log("runner"),
+    ...projectDir !== undefined ? { projectDir } : {},
     reporter: buildRunReporter(flags, {
       fs: ctx.fs,
       stdout: { write: (text3) => ctx.ui.write(text3) },
@@ -185057,11 +185176,11 @@ function buildFlowsRunDeps(args) {
 
 // src/commands/flows/loadEnvFile.ts
 import { readFile } from "node:fs/promises";
-import { join as join37 } from "node:path";
+import { join as join38 } from "node:path";
 async function loadEnvFile(envDir) {
   let content;
   try {
-    content = await readFile(join37(envDir, ".env"), "utf8");
+    content = await readFile(join38(envDir, ".env"), "utf8");
   } catch (err) {
     if (isNoEntError(err))
       return;
@@ -185106,6 +185225,14 @@ async function runStagedFlows(args) {
     for (const candidate of staged.outerHop.rejected) {
       log31.debug(runnerMessages.outerHopCandidateRejected(candidate.dir, candidate.missing));
     }
+    const ownModules = projectDir === undefined ? undefined : join39(projectDir, "node_modules");
+    const own = staged.outerHop.rejected.find((c3) => c3.dir === ownModules);
+    if (own !== undefined) {
+      ctx.ui.warn(runnerMessages.outerHopFallbackNotice(own.dir, own.missing));
+    }
+    if (staged.outerHop.carriedOver.length > 0) {
+      ctx.ui.warn(runnerMessages.outerHopCarriedOver(staged.outerHop.carriedOver));
+    }
   }
   const unregisterCleanup = ctx.signals.register(staged.cleanup);
   try {
@@ -185162,7 +185289,7 @@ async function handleFlowsRun(ctx, pattern, flags, deps) {
 }
 
 // src/commands/flows/hybridRunDefaults.ts
-import { join as join38, resolve as resolve10 } from "node:path";
+import { join as join40, resolve as resolve10 } from "node:path";
 function makeDefaultHybridDeps(fs9) {
   return {
     expandPatterns: (patterns, cwd, logger) => expandPatterns(patterns, cwd, logger, fs9),
@@ -185181,7 +185308,7 @@ async function handleHybridFlowsRun(ctx, pattern, flags, deps) {
   if (validation !== "ok") {
     return { error: validation.error, exitCode: 2 };
   }
-  const envDir = resolve10(join38(".qawolf", flags.env));
+  const envDir = resolve10(join40(".qawolf", flags.env));
   const patternArgs = buildPatternArgs(pattern);
   const globFlows = () => resolvedDeps.expandPatterns(patternArgs, envDir, ctx.log("flows"));
   let files = await globFlows();
@@ -185327,12 +185454,12 @@ function registerFlowsCommand(program2, signals) {
 }
 
 // src/domains/init/init.ts
-import { dirname as dirname13, join as join40, relative as relative7 } from "node:path";
+import { dirname as dirname14, join as join42, relative as relative7 } from "node:path";
 
 // src/domains/init/ensurePackageJson.ts
-import { join as join39 } from "node:path";
+import { join as join41 } from "node:path";
 async function ensurePackageJson(ctx, yes, deps) {
-  const pkgPath = join39(deps.cwd, "package.json");
+  const pkgPath = join41(deps.cwd, "package.json");
   if (!await deps.fs.pathExists(pkgPath)) {
     const confirmed2 = await ctx.ui.confirm(initMessages.createPackageJsonPrompt, { yes });
     if (!confirmed2.ok || !confirmed2.value) {
@@ -185458,9 +185585,9 @@ function makeDefaultInitDeps() {
 async function handleInit(ctx, opts, deps = makeDefaultInitDeps()) {
   ctx.ui.gap();
   ctx.ui.intro(initMessages.title);
-  const configPath = join40(deps.cwd, "qawolf.config.ts");
-  const flowPath = join40(deps.cwd, "src", "flows", "example.flow.ts");
-  const gitignorePath = join40(deps.cwd, ".qawolf", ".gitignore");
+  const configPath = join42(deps.cwd, "qawolf.config.ts");
+  const flowPath = join42(deps.cwd, "src", "flows", "example.flow.ts");
+  const gitignorePath = join42(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);
@@ -185479,7 +185606,7 @@ async function writeWithPrompt(ctx, filePath, content, yes, deps) {
       return;
     }
   }
-  await deps.fs.mkdir(dirname13(filePath), { recursive: true });
+  await deps.fs.mkdir(dirname14(filePath), { recursive: true });
   await deps.fs.writeFile(filePath, content);
   ctx.ui.step(initMessages.createdFile(relPath));
 }
@@ -185498,7 +185625,7 @@ Examples:
 import { parseExecutionTarget as parseExecutionTarget4 } from "@qawolf/flow-targets";
 
 // src/domains/install/android/avd.ts
-import { join as join41 } from "node:path";
+import { join as join43 } from "node:path";
 async function installAvds(ctx, specs, deps) {
   const sdkManagerPath = sdkManagerBin(deps.androidHome, deps.platform);
   const avdManagerPath = avdManagerBin(deps.androidHome, deps.platform);
@@ -185508,7 +185635,7 @@ async function installAvds(ctx, specs, deps) {
   if (versionResult.exitCode !== 0) {
     throw new Error(installMessages.android.sdkmanagerNotFound(sdkManagerPath));
   }
-  const licenseFile = join41(deps.androidHome, "licenses", "android-sdk-license");
+  const licenseFile = join43(deps.androidHome, "licenses", "android-sdk-license");
   if (deps.checkExists(licenseFile)) {
     ctx.ui.info(installMessages.android.licensesAlreadyAccepted);
   } else {
@@ -185523,7 +185650,7 @@ async function installAvds(ctx, specs, deps) {
   for (const spec of specs) {
     if (installedImages.has(spec.systemImage))
       continue;
-    const systemImg = join41(deps.androidHome, ...spec.systemImage.split(";"), "system.img");
+    const systemImg = join43(deps.androidHome, ...spec.systemImage.split(";"), "system.img");
     if (deps.checkExists(systemImg)) {
       ctx.ui.info(installMessages.android.systemImageAlreadyInstalled(spec.systemImage));
       installedImages.add(spec.systemImage);
@@ -185970,6 +186097,14 @@ function flagUsage(field, kind) {
     return `${name} <KEY=VALUE...>`;
   return `${name} <value>`;
 }
+function describeFlag(schema) {
+  const description = schema.description ?? "";
+  const values = schema.enum ?? schema.items?.enum;
+  if (!values?.length)
+    return description;
+  const choices = `One of: ${values.join(", ")}`;
+  return description ? `${description} ${choices}` : choices;
+}
 function buildFlagSpecs(inputSchema) {
   const jsonSchema = exports_external.toJSONSchema(inputSchema, {
     io: "input"
@@ -185985,7 +186120,7 @@ function buildFlagSpecs(inputSchema) {
     flags.push({
       field,
       flag: flagUsage(field, kind.kind),
-      description: fieldSchema.description ?? "",
+      description: describeFlag(fieldSchema),
       required: result.shape.required.has(field),
       kind: kind.kind
     });
@@ -186092,7 +186227,7 @@ async function handlePublicApiCommand(ctx, spec, options) {
 }
 
 // src/domains/publicApi/skippedContracts.ts
-var handWrittenContractNames = new Set([
+var skippedContractNames = new Set([
   "flow.list",
   "runner.evaluateSnippet",
   "runner.launch",
@@ -186102,13 +186237,6 @@ var handWrittenContractNames = new Set([
   "runner.stop",
   "runner.takeScreenshot"
 ]);
-var unexpressibleContractNames = new Set([
-  "issue.update"
-]);
-var skippedContractNames = new Set([
-  ...handWrittenContractNames,
-  ...unexpressibleContractNames
-]);
 
 // src/commands/publicApi/index.ts
 var groupDescriptions = {
@@ -186574,7 +186702,7 @@ async function handleRunnerScreenshot(ctx, options, deps) {
 }
 
 // src/shell/interactiveRunner/collectRunFiles.ts
-import { join as join42 } from "node:path";
+import { join as join44 } from "node:path";
 async function collectRunFiles(options) {
   const paths = await glob(shippableRunFileExtensions.map((extension) => `**/*${extension}`), {
     cwd: options.cwd,
@@ -186584,7 +186712,7 @@ async function collectRunFiles(options) {
   const shippable = paths.filter(isShippableRunFilePath).sort();
   const files = {};
   const read = batchMap(shippable, async (path9) => ({
-    content: await options.fs.readFile(join42(options.cwd, path9)),
+    content: await options.fs.readFile(join44(options.cwd, path9)),
     path: path9
   }), flowBatchSize);
   for await (const file2 of read)
@@ -186599,7 +186727,7 @@ function makeRunnerId() {
 }
 
 // src/shell/interactiveRunner/runnerStore.ts
-import { join as join43 } from "node:path";
+import { join as join45 } from "node:path";
 var storeFileName = "runner.json";
 var storeSchema = exports_external.object({ defaultRunnerId: exports_external.string().optional() });
 function parseJson(text3) {
@@ -186610,8 +186738,8 @@ function parseJson(text3) {
   }
 }
 function makeRunnerStore(options) {
-  const directory = join43(options.cwd, qawolfDir);
-  const path9 = join43(directory, storeFileName);
+  const directory = join45(options.cwd, qawolfDir);
+  const path9 = join45(directory, storeFileName);
   let pendingWrites = 0;
   const nextPendingPath = () => `${path9}.${process.pid}.${++pendingWrites}.tmp`;
   return {
@@ -186638,7 +186766,7 @@ function makeRunnerStore(options) {
 }
 
 // src/shell/interactiveRunner/writeScreenshot.ts
-import { dirname as dirname14 } from "node:path";
+import { dirname as dirname15 } from "node:path";
 var jpegStartOfImage = [255, 216, 255];
 async function writeScreenshot(options) {
   const bytes = Buffer.from(options.imageJpegBase64, "base64");
@@ -186646,7 +186774,7 @@ async function writeScreenshot(options) {
     return { ok: false, reason: "not-a-jpeg" };
   }
   try {
-    await options.fs.mkdir(dirname14(options.path), { recursive: true });
+    await options.fs.mkdir(dirname15(options.path), { recursive: true });
     await options.fs.writeFile(options.path, bytes);
   } catch (error51) {
     return { detail: errorMessage(error51), ok: false, reason: "unwritable" };
@@ -187284,4 +187412,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => flushAndExit(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=8CB687F9691544E564756E2164756E21
+//# debugId=0187A36B3165B15F64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.10.0",
+  "version": "1.11.2",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -68,7 +68,6 @@
     "appium": "2.11.3",
     "commander": "14.0.3",
     "env-paths": "4.0.0",
-    "expect-webdriverio": "5.6.5",
     "picomatch": "4.0.4",
     "pino": "10.3.1",
     "playwright": "1.62.0",
@@ -85,6 +84,7 @@
     "@types/bun": "1.3.14",
     "@types/picomatch": "4.0.3",
     "appium-uiautomator2-driver": "4.2.9",
+    "expect-webdriverio": "5.6.5",
     "knip": "6.16.1",
     "oxfmt": "0.54.0",
     "oxlint": "1.69.0",

package/skills/qawolf-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qawolf-cli
-description: Manage QA Wolf through the qawolf CLI. Use when asked which QA Wolf environment variables are available or to list, set, or delete them; manage environments, flows, runs, tags, or issues; authenticate; install; run or list flows; or drive a live cloud browser (launch a runner, screenshot it, click and type on it, read its recorder) from a shell.
+description: Manage QA Wolf through the qawolf CLI. Use when asked to create, update, or list coverage requests, bug reports, or maintenance reports; start a run of flows or tags on the QA Wolf platform or read a run's results; list, set, or delete environment variables; manage environments, flows, or tags; request automation of draft flows; run or list flows locally; authenticate; install the local runtime; or drive a live cloud browser (launch a runner, screenshot it, click and type on it, read its recorder) from a shell.
 license: Apache-2.0
 compatibility: Requires the qawolf CLI on PATH. Install it from @qawolf/cli or use a standalone binary from GitHub Releases.
 ---
@@ -72,6 +72,15 @@ each printed line from the payload alone to the whole envelope (`sequence`,
 `recordedAt`, `payload`). Both are JSON. Pass it when you want to page by
 sequence, omit it when you want the payloads themselves.
 
+A `--json` response shows you most of its own shape, so read it first.
+
+`qawolf run get` is the exception worth reading about before you use it. Its
+artifact URLs expire, its failure fields are absent from a passing run, and its
+`traceUrl` downloads a Playwright trace that you can read as JSON without
+opening the trace viewer. **Read
+[`references/run-results.md`](references/run-results.md) before reporting on a
+run's outcome or opening its trace.**
+
 ## Safety: reads vs writes
 
 Read commands do not change team data, but some have operational effects noted
@@ -127,6 +136,7 @@ current branch.
 | `qawolf issue create` | write | Create a bug or coverage request issue for the caller's team. Maintenance issues cannot be created through the public API. |
 | `qawolf issue find` | read | List the team's bug reports, maintenance reports, or coverage requests, newest first. |
 | `qawolf issue get` | read | Get an issue by id. |
+| `qawolf issue update` | write | Update an issue owned by the caller's team. Omitted fields remain unchanged. |
 | `qawolf run create` | write | Create a run for the selected flows and/or tags in an environment. |
 | `qawolf run find` | read | List an environment's recent runs, newest first. |
 | `qawolf run get` | read | Get a run's status, per-flow results, and links. |

package/skills/qawolf-cli/references/run-results.md

@@ -0,0 +1,169 @@
+# Reading a run's results
+
+How to use what `qawolf run get --run-id <id> --json` returns, and how to read
+the Playwright trace it links to.
+
+Call `run get` with `--json` and you see most of the response immediately. Read
+this file for the parts a single response cannot show you: fields that appear
+only when something fails, rules about the artifact URLs, and how to read a
+trace without opening the trace viewer.
+
+## The shape
+
+A run holds flows, a flow holds attempts, and artifacts hang off an attempt:
+
+```text
+run
+└── flows[]
+    ├── failure          only when the flow failed
+    └── attempts[]       oldest first
+        ├── logsUrl
+        ├── traceUrl
+        └── videoUrl
+```
+
+`runId` in the response is canonical and can differ from the id you asked for.
+Use the returned value for follow-up calls.
+
+Poll `status` until it reaches `passed`, `failed` or `canceled`. The other
+values mean the run is still going.
+
+## Fields a passing run does not show you
+
+- `flows[].failure` exists only when a flow failed. Every flow passing means
+  there is no failure object at all, so its diagnosis and issue id are invisible
+  until something breaks. Do not conclude the field does not exist.
+- `git` is populated only when a deploy notification started the run. A run
+  started manually or with `run create` has an empty object here.
+- An attempt's `kind` and `status` select which other fields it has. Only
+  automated attempts that reached a verdict carry artifact URLs; canceled
+  attempts and manual Wolf Browser attempts carry none.
+- A flow that passed after a retry still lists its failed attempts. Read the
+  last attempt for the outcome, and the earlier ones to see what went wrong.
+
+## Artifact URLs
+
+Each automated attempt links `logsUrl` (execution logs), `videoUrl` (screen
+recording) and `traceUrl` (a Playwright `trace.zip`).
+
+1. They are signed URLs with a limited life. The contract guarantees at least a
+   day. Call `run get` again for fresh ones instead of storing them; a stored
+   URL becomes a dead link.
+2. A URL can return 404 when that attempt did not produce that artifact. Handle
+   the 404 rather than treating the URL's presence as a guarantee of content.
+3. Download with a plain HTTP GET. The signature is in the URL, so no
+   authentication header is needed and no QA Wolf credentials are involved.
+
+```bash
+qawolf run get --run-id "$RUN_ID" --json \
+  | jq -r '.flows[].attempts[-1].traceUrl // empty' \
+  | head -1 \
+  | xargs -r curl -sS -o trace.zip
+```
+
+## Reading the Playwright trace
+
+The usual advice is `npx playwright show-trace trace.zip`, which opens a
+browser window. That is useless in a shell and unnecessary: the zip holds
+newline-delimited JSON files, and reading them directly is faster than
+downloading a viewer.
+
+The zip holds `trace.trace` (the events), `trace.network` (one request and
+response per line) and a `resources/` directory of screencast frames. The
+frames are most of the size, so extract only what you need.
+
+### The event types
+
+Every line of `trace.trace` is one JSON object with a `type`:
+
+- `before` — a call started. Carries `callId`, `startTime`, `class`, `method`
+  and `params`. `params.selector` or `params.url` is usually the target.
+- `after` — that call finished. Matched to its `before` by `callId`. Carries
+  `endTime` and `result`, and an `error` when the call failed.
+- `console` — a browser console message, with `messageType` and `text`.
+- `log` — Playwright's own progress notes for a call.
+- `screencast-frame`, `frame-snapshot` — the filmstrip and DOM snapshots the
+  viewer renders. Usually not worth reading directly.
+
+Two details cost time if you miss them:
+
+- **Times are monotonic milliseconds, not seconds.** A `goto` whose `startTime`
+  and `endTime` differ by `161.6` took 161 milliseconds. Subtract the smallest
+  `startTime` to get an offset from the start of the trace.
+- **Return values use a serialized envelope.** `{"value":{"s":"passed"}}` is
+  the string `passed`, `{"n":640}` is the number `640`, and `{"o":[...]}` is an
+  object as a list of key and value pairs.
+
+### A worked example
+
+Pairing `before` with `after` gives an action timeline with durations and
+failures:
+
+```python
+import json, sys, zipfile
+
+with zipfile.ZipFile(sys.argv[1]) as z:
+    events = [json.loads(line) for line in z.read("trace.trace").decode().splitlines()]
+
+starts = {e["callId"]: e for e in events if e["type"] == "before"}
+ends = {e["callId"]: e for e in events if e["type"] == "after"}
+t0 = min(e["startTime"] for e in starts.values())
+
+for call_id, before in starts.items():
+    after = ends.get(call_id, {})
+    params = before.get("params", {})
+    target = params.get("selector") or params.get("url") or ""
+    error = after.get("error")
+    print(
+        f'{(before["startTime"] - t0) / 1000:7.2f}s'
+        f' {after.get("endTime", before["startTime"]) - before["startTime"]:7.1f}ms'
+        f'  {before["class"]}.{before["method"]:<18} {target[:40]}'
+        f'{"  FAILED: " + json.dumps(error)[:60] if error else ""}'
+    )
+
+for e in events:
+    if e["type"] == "console" and e["messageType"] == "error":
+        print(f'console error: {e["text"][:70]}')
+```
+
+It prints one line per call, in order:
+
+```text
+   0.00s   161.6ms  Frame.goto               https://example.com/
+   0.17s    28.3ms  Frame.waitForSelector    #screen
+   0.20s     4.2ms  Frame.innerText          #fps_stats
+console error: Failed to load resource: the server responded with a status of 404 ()
+```
+
+To find why an attempt failed, read the last `after` that carries an `error`,
+then the `console` errors near it in time. To see what the page did, read
+`trace.network`.
+
+## Response fields
+
+Every documented field of the `run.get` response. `[]` marks an array, so
+`flows[].attempts[].traceUrl` is the trace URL of one attempt of one flow.
+
+<!-- fields:start — generated by `bun run generate`, do not edit -->
+
+- `completedAt` — 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).
+- `git` — 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.
+- `git.commitUrl` — Link to the commit on the code host.
+- `runId` — The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.
+- `status` — One of: queued, running, passed, failed, canceled
+- `flows` — The run's flows, ordered alphabetically by name.
+- `flows[].attempts` — The flow's finished execution attempts, oldest first, including manual Wolf Browser attempts. Present once at least one attempt has finished, so a flow that passed after retries also lists its failed attempts. Artifact URLs appear only on automated attempts that reached a verdict, stay valid for at least a day (call run.get again for fresh ones), and can return 404 when the attempt did not produce that artifact.
+- `flows[].attempts[].logsUrl` — Signed URL for the attempt's execution logs.
+- `flows[].attempts[].traceUrl` — Signed URL for the attempt's Playwright trace (a trace.zip; open it with `npx playwright show-trace`).
+- `flows[].attempts[].videoUrl` — Signed URL for the attempt's screen recording.
+- `flows[].attempts[].kind` — One of: automated, manual
+- `flows[].attempts[].startedAt` — Absent when the attempt failed before it could start.
+- `flows[].attempts[].status` — One of: passed, failed, canceled
+- `flows[].failure.diagnosis` — QA Wolf's investigation verdict for the failure: `bug` means the application is broken, `maintenance` means the test needed an update and the failure does not indicate an application problem. Absent until the investigation reaches a verdict. Pass issueId to issue.get for details.
+- `flows[].failure.diagnosis.issueId` — The id of the issue.
+- `flows[].failure.diagnosis.type` — One of: bug, maintenance
+- `flows[].flowId` — The id of the flow.
+- `flows[].status` — One of: failed, queued, running, passed, canceled
+- `url` — Absolute URL of the run page.
+
+<!-- fields:end -->