@piwitests/reporter 0.45.0 → 0.46.0

package/dist/cli/index.js

@@ -261,7 +261,7 @@ function checkAiTree(root, opts = {}) {
           severity: "error",
           kind: "non-canonical",
           file: rel(found.file),
-          message: "file is not in canonical form \u2014 run `piwi ai prune --apply` or re-resolve to rewrite it"
+          message: "file is not in canonical form \u2014 re-author it with `piwi ai resolve --update-ai`"
         });
       }
       if (!sourceCache.has(found.specFile)) sourceCache.set(found.specFile, readTextOr(found.specFile, null));
@@ -428,7 +428,9 @@ async function runAi(argv, env = process.env) {
     case "resolve":
       return runResolve(rest, env);
     case "prune":
-      console.error("piwi ai prune: three-tier cleanup is not available in this build yet.");
+      console.error(
+        "piwi ai prune: not available in this build yet. `piwi ai check` lists orphaned entries: delete their files by hand, and re-author a non-canonical one with `piwi ai resolve --update-ai`."
+      );
       return EXIT_ERROR;
     default:
       console.error(`piwi ai: unknown command "${sub}"
@@ -439,10 +441,164 @@ async function runAi(argv, env = process.env) {
 }
 
 // src/cli/bug.ts
-var fs3 = __toESM(require("fs"));
-var path6 = __toESM(require("path"));
+var fs4 = __toESM(require("fs"));
+var path7 = __toESM(require("path"));
 var import_node_child_process2 = require("child_process");
 var import_node_module = require("module");
+
+// src/internal/config/desktop.ts
+var fs3 = __toESM(require("fs"));
+var os = __toESM(require("os"));
+var path6 = __toESM(require("path"));
+function defaultDesktopConfigPath() {
+  return path6.join(os.homedir(), ".piwi", "desktop.json");
+}
+function readDesktopConfig(filePath) {
+  try {
+    const parsed = JSON.parse(fs3.readFileSync(filePath, "utf8"));
+    const url = parsed?.url;
+    const token = parsed?.token;
+    if (typeof url !== "string" || !url) return null;
+    if (typeof token !== "string" || !token) return null;
+    return { url, token };
+  } catch {
+    return null;
+  }
+}
+
+// src/internal/config/env.ts
+var DEFAULTS = {
+  projectName: "default-project",
+  uploadTraces: true,
+  uploadReport: true,
+  liveFileUploads: true,
+  collectScmInfo: true,
+  collectCiInfo: true,
+  collectPerformanceMetrics: true,
+  captureLocators: true,
+  capturePageState: true,
+  // Off by default: the page inventory reads control and link names from every
+  // visited page, so it stays opt-in until a project turns it on.
+  capturePageInventory: false,
+  // Off by default: JavaScript coverage slows the page, so a scheduled job opts in.
+  captureCodeReach: false,
+  captureServerTraces: true,
+  captureResources: true,
+  leakCheck: "report",
+  sampleAriaOnPass: true,
+  uploadManifest: true,
+  defaultCapture: true,
+  checkBaseUrl: false,
+  streaming: true,
+  streamingBatchSize: 5,
+  streamingBatchDelay: 2e3,
+  maxStreamBufferBytes: 100 * 1024 * 1024,
+  submitTimeout: 15 * 60 * 1e3,
+  failOnFlakyTests: false,
+  username: null,
+  password: null,
+  apiKey: null,
+  verbose: false
+};
+var PIWI_ENV_KEYS = {
+  serverUrl: "PIWI_DASHBOARD_URL",
+  projectName: "PIWI_PROJECT_NAME",
+  verbose: "PIWI_VERBOSE",
+  apiKey: "PIWI_API_KEY",
+  username: "PIWI_USERNAME",
+  password: "PIWI_PASSWORD",
+  environment: "PIWI_ENVIRONMENT",
+  label: "PIWI_LABEL",
+  runLabel: "PIWI_RUN_LABEL",
+  keep: "PIWI_KEEP",
+  streaming: "PIWI_STREAMING",
+  streamingBatchSize: "PIWI_STREAMING_BATCH_SIZE",
+  streamingBatchDelay: "PIWI_STREAMING_BATCH_DELAY",
+  maxStreamBufferBytes: "PIWI_MAX_STREAM_BUFFER_BYTES",
+  submitTimeout: "PIWI_SUBMIT_TIMEOUT",
+  liveFileUploads: "PIWI_LIVE_FILE_UPLOADS",
+  failOnFlakyTests: "PIWI_FAIL_ON_FLAKY_TESTS",
+  uploadTraces: "PIWI_UPLOAD_TRACES",
+  uploadReport: "PIWI_UPLOAD_REPORT",
+  captureLocators: "PIWI_CAPTURE_LOCATORS",
+  capturePageState: "PIWI_CAPTURE_PAGE_STATE",
+  capturePageInventory: "PIWI_CAPTURE_PAGE_INVENTORY",
+  captureCodeReach: "PIWI_CAPTURE_CODE_REACH",
+  codeReachRoots: "PIWI_CODE_REACH_ROOTS",
+  captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
+  captureResources: "PIWI_CAPTURE_RESOURCES",
+  leakCheck: "PIWI_LEAK_CHECK",
+  sampleAriaOnPass: "PIWI_SAMPLE_ARIA_ON_PASS",
+  uploadManifest: "PIWI_UPLOAD_MANIFEST",
+  defaultCapture: "PIWI_DEFAULT_CAPTURE",
+  checkBaseUrl: "PIWI_CHECK_BASE_URL",
+  inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
+  pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
+  outputFile: "PIWI_OUTPUT_FILE",
+  aiMode: "PIWI_AI",
+  aiDir: "PIWI_AI_DIR",
+  aiOnMiss: "PIWI_AI_ON_MISS",
+  aiMaxSteps: "PIWI_AI_MAX_FLOW_STEPS",
+  aiMaxSnapshotChars: "PIWI_AI_MAX_SNAPSHOT_CHARS",
+  aiOptionalProbeTimeout: "PIWI_AI_OPTIONAL_PROBE_TIMEOUT",
+  aiResponseWaitTimeout: "PIWI_AI_RESPONSE_WAIT_TIMEOUT",
+  aiScreenshotFallback: "PIWI_AI_SCREENSHOT_FALLBACK"
+};
+var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
+var PIWI_ORIGIN_ENV = {
+  kind: "PIWI_ORIGIN",
+  ref: "PIWI_ORIGIN_REF"
+};
+function originEnv(kind, ref) {
+  return ref === void 0 ? { [PIWI_ORIGIN_ENV.kind]: kind } : { [PIWI_ORIGIN_ENV.kind]: kind, [PIWI_ORIGIN_ENV.ref]: String(ref) };
+}
+var PIWI_SHARD_ENV = "PIWI_SHARD";
+var PIWI_PROBE_ENV = {
+  flag: "PIWI_PROBE",
+  plan: "PIWI_PROBE_PLAN",
+  results: "PIWI_PROBE_RESULTS",
+  secret: "PIWI_PROBE_SECRET"
+};
+var PIWI_FLAKE_ENV = {
+  plan: "PIWI_FLAKE_PLAN",
+  results: "PIWI_FLAKE_RESULTS"
+};
+var ENV_FALLBACK_SPECS = [
+  { option: "serverUrl", env: PIWI_ENV_KEYS.serverUrl, kind: "string" },
+  { option: "projectName", env: PIWI_ENV_KEYS.projectName, kind: "string" },
+  { option: "apiKey", env: PIWI_ENV_KEYS.apiKey, kind: "string" },
+  { option: "username", env: PIWI_ENV_KEYS.username, kind: "string" },
+  { option: "password", env: PIWI_ENV_KEYS.password, kind: "string" },
+  { option: "environment", env: PIWI_ENV_KEYS.environment, kind: "string" },
+  { option: "label", env: PIWI_ENV_KEYS.label, kind: "string" },
+  { option: "runLabel", env: PIWI_ENV_KEYS.runLabel, kind: "string" },
+  { option: "keep", env: PIWI_ENV_KEYS.keep, kind: "bool" },
+  { option: "streaming", env: PIWI_ENV_KEYS.streaming, kind: "bool" },
+  { option: "streamingBatchSize", env: PIWI_ENV_KEYS.streamingBatchSize, kind: "number" },
+  { option: "streamingBatchDelay", env: PIWI_ENV_KEYS.streamingBatchDelay, kind: "number" },
+  { option: "maxStreamBufferBytes", env: PIWI_ENV_KEYS.maxStreamBufferBytes, kind: "number" },
+  { option: "submitTimeout", env: PIWI_ENV_KEYS.submitTimeout, kind: "number" },
+  { option: "liveFileUploads", env: PIWI_ENV_KEYS.liveFileUploads, kind: "bool" },
+  { option: "failOnFlakyTests", env: PIWI_ENV_KEYS.failOnFlakyTests, kind: "bool" },
+  { option: "uploadTraces", env: PIWI_ENV_KEYS.uploadTraces, kind: "bool" },
+  { option: "uploadReport", env: PIWI_ENV_KEYS.uploadReport, kind: "bool" },
+  { option: "captureLocators", env: PIWI_ENV_KEYS.captureLocators, kind: "bool" },
+  { option: "capturePageState", env: PIWI_ENV_KEYS.capturePageState, kind: "bool" },
+  { option: "capturePageInventory", env: PIWI_ENV_KEYS.capturePageInventory, kind: "bool" },
+  { option: "captureCodeReach", env: PIWI_ENV_KEYS.captureCodeReach, kind: "bool" },
+  { option: "captureServerTraces", env: PIWI_ENV_KEYS.captureServerTraces, kind: "bool" },
+  { option: "captureResources", env: PIWI_ENV_KEYS.captureResources, kind: "bool" },
+  { option: "leakCheck", env: PIWI_ENV_KEYS.leakCheck, kind: "string" },
+  { option: "sampleAriaOnPass", env: PIWI_ENV_KEYS.sampleAriaOnPass, kind: "bool" },
+  { option: "uploadManifest", env: PIWI_ENV_KEYS.uploadManifest, kind: "bool" },
+  { option: "defaultCapture", env: PIWI_ENV_KEYS.defaultCapture, kind: "bool" },
+  { option: "checkBaseUrl", env: PIWI_ENV_KEYS.checkBaseUrl, kind: "bool" },
+  { option: "inspectOnFailure", env: PIWI_ENV_KEYS.inspectOnFailure, kind: "bool" },
+  { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" },
+  { option: "outputFile", env: PIWI_ENV_KEYS.outputFile, kind: "string" }
+];
+
+// src/cli/bug.ts
 var EXIT_OK2 = 0;
 var EXIT_RUN_FAILED = 1;
 var EXIT_ERROR2 = 2;
@@ -535,7 +691,7 @@ function repositoryRoot(cwd) {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
-    return out ? path6.resolve(out) : null;
+    return out ? path7.resolve(out) : null;
   } catch {
     return null;
   }
@@ -543,23 +699,23 @@ function repositoryRoot(cwd) {
 function realFolder(dir) {
   const rest = [];
   let current = dir;
-  while (!fs3.existsSync(current) && path6.dirname(current) !== current) {
-    rest.unshift(path6.basename(current));
-    current = path6.dirname(current);
+  while (!fs4.existsSync(current) && path7.dirname(current) !== current) {
+    rest.unshift(path7.basename(current));
+    current = path7.dirname(current);
   }
-  return path6.join(fs3.realpathSync(current), ...rest);
+  return path7.join(fs4.realpathSync(current), ...rest);
 }
 function folderInRepository(root, dir) {
-  const relative6 = path6.relative(realFolder(root), realFolder(dir));
-  if (relative6.startsWith("..") || path6.isAbsolute(relative6)) return void 0;
-  return relative6.split(path6.sep).join("/");
+  const relative6 = path7.relative(realFolder(root), realFolder(dir));
+  if (relative6.startsWith("..") || path7.isAbsolute(relative6)) return void 0;
+  return relative6.split(path7.sep).join("/");
 }
 function fileFilter(file) {
   const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return `${escape(path6.basename(path6.dirname(file)))}[\\\\/]${escape(path6.basename(file))}$`;
+  return `${escape(path7.basename(path7.dirname(file)))}[\\\\/]${escape(path7.basename(file))}$`;
 }
 function resolvePlaywrightCli(cwd) {
-  const require2 = (0, import_node_module.createRequire)(path6.join(cwd, "noop.js"));
+  const require2 = (0, import_node_module.createRequire)(path7.join(cwd, "noop.js"));
   for (const id of ["playwright/cli", "@playwright/test/cli", "playwright/lib/cli/cli"]) {
     try {
       return require2.resolve(id);
@@ -568,12 +724,14 @@ function resolvePlaywrightCli(cwd) {
   }
   return null;
 }
-function runPlaywright(file, cwd) {
+function runPlaywright(file, cwd, id, env) {
   const cli = resolvePlaywrightCli(cwd);
   const filter = fileFilter(file);
-  const child = cli ? (0, import_node_child_process2.spawn)(process.execPath, [cli, "test", filter], { stdio: "inherit", cwd }) : (0, import_node_child_process2.spawn)(process.platform === "win32" ? "npx.cmd" : "npx", ["playwright", "test", filter], {
+  const childEnv = { ...env, ...originEnv("bug", id) };
+  const child = cli ? (0, import_node_child_process2.spawn)(process.execPath, [cli, "test", filter], { stdio: "inherit", cwd, env: childEnv }) : (0, import_node_child_process2.spawn)(process.platform === "win32" ? "npx.cmd" : "npx", ["playwright", "test", filter], {
     stdio: "inherit",
-    cwd
+    cwd,
+    env: childEnv
   });
   return new Promise((resolve8) => {
     child.on("error", (err) => {
@@ -598,10 +756,10 @@ ${USAGE2}`);
     return EXIT_ERROR2;
   }
   const root = args.write ? repositoryRoot(cwd) : null;
-  const outFile = args.out !== null ? path6.resolve(cwd, args.out) : null;
+  const outFile = args.out !== null ? path7.resolve(cwd, args.out) : null;
   let spec;
   try {
-    spec = await fetchBugSpec(args, outFile && root ? folderInRepository(root, path6.dirname(outFile)) : void 0);
+    spec = await fetchBugSpec(args, outFile && root ? folderInRepository(root, path7.dirname(outFile)) : void 0);
   } catch (e) {
     console.error(`piwi bug: ${e.message}`);
     return EXIT_ERROR2;
@@ -616,19 +774,19 @@ ${USAGE2}`);
   if (!outFile && !root) {
     console.error("piwi bug: not in a git repository \u2014 the bugs folder is read from the working directory");
   }
-  const file = outFile ?? path6.resolve(root ?? cwd, spec.path);
+  const file = outFile ?? path7.resolve(root ?? cwd, spec.path);
   try {
-    fs3.mkdirSync(path6.dirname(file), { recursive: true });
-    fs3.writeFileSync(file, spec.code, { flag: args.force ? "w" : "wx" });
+    fs4.mkdirSync(path7.dirname(file), { recursive: true });
+    fs4.writeFileSync(file, spec.code, { flag: args.force ? "w" : "wx" });
   } catch (e) {
     const exists = e.code === "EEXIST";
     console.error(`piwi bug: ${exists ? `${file} exists \u2014 pass --force to replace it` : e.message}`);
     return EXIT_ERROR2;
   }
-  const shown = path6.relative(cwd, file) || file;
+  const shown = path7.relative(cwd, file) || file;
   console.error(`piwi bug: wrote ${shown}`);
   if (!args.run) return EXIT_OK2;
-  const code = await runPlaywright(file, cwd);
+  const code = await runPlaywright(file, cwd, args.id, env);
   if (code === EXIT_ERROR2 && !resolvePlaywrightCli(cwd)) return EXIT_ERROR2;
   if (code === 0) {
     console.error(
@@ -643,8 +801,8 @@ ${USAGE2}`);
 }
 
 // src/cli/codegen.ts
-var fs4 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
+var fs5 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
 
 // ../core/src/recording.ts
 var ASSERTION_MATCHERS = [
@@ -717,13 +875,20 @@ function extractArgs(entry, window, pairs) {
   }
   return args;
 }
+function sameElement(pattern, recorded) {
+  if (pattern.testId || !pattern.name) return true;
+  const haystack = `${recorded?.accessibleName ?? ""} ${recorded?.text ?? ""}`.toLowerCase().trim();
+  const needle = pattern.name.toLowerCase();
+  return haystack.length > 0 && (haystack.includes(needle) || needle.includes(haystack));
+}
 function contiguousAlignment(steps, startIndex, pattern) {
   if (startIndex + pattern.length > steps.length) return null;
   const pairs = [];
   let total = 0;
   for (let j = 0; j < pattern.length; j++) {
-    const score = stepPairScore(pattern[j], steps[startIndex + j]);
-    if (score <= 0) return null;
+    const recorded = steps[startIndex + j];
+    const score = stepPairScore(pattern[j], recorded);
+    if (score <= 0 || !sameElement(pattern[j].target, recorded.target)) return null;
     total += score;
     pairs.push([j, j]);
   }
@@ -1549,6 +1714,41 @@ function pageUrlPattern(url) {
 function commentText(s) {
   return s.replace(/[\n\r\u2028\u2029]+/g, " ").trim();
 }
+var ENV_NAME_MAX = 40;
+function envPrefixOf(options) {
+  const prefix = options.envPrefix;
+  return typeof prefix === "string" && ENV_PREFIX.test(prefix) ? prefix : "E2E_";
+}
+var ENV_PREFIX = /^[A-Z][A-Z0-9_]*$/;
+function envNameOf(target, prefix) {
+  for (const source of [target?.accessibleName, target?.testId, target?.text]) {
+    const name = (source ?? "").normalize("NFKD").replace(new RegExp("\\p{M}", "gu"), "").toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, ENV_NAME_MAX).replace(/_+$/, "");
+    if (name) return `${prefix}${name}`;
+  }
+  return `${prefix}VALUE`;
+}
+function uniqueEnvName(name, taken) {
+  if (!taken.includes(name)) return name;
+  let n = 2;
+  while (taken.includes(`${name}_${n}`)) n++;
+  return `${name}_${n}`;
+}
+function envVarFor(step, index, ctx) {
+  const envVar = uniqueEnvName(envNameOf(step.target, envPrefixOf(ctx.options)), ctx.envNames);
+  ctx.envNames.push(envVar);
+  if (step.redacted) {
+    ctx.warnings.push({
+      step: index,
+      code: "redacted-value",
+      detail: envVar,
+      message: `A password was typed here; the spec reads it from ${envVar}.`
+    });
+  }
+  return envVar;
+}
+function readsEnv(step, ctx) {
+  return step.action === "fill" && (step.redacted || ctx.options.values === "env");
+}
 function urlForCode(url, ctx) {
   const isPath = url.startsWith("/");
   if (ctx.options.urls === "relative") {
@@ -1566,7 +1766,7 @@ function locatorForStep(step, index, ctx) {
   const chosen = chooseLocator(step.target, ctx.options);
   if (!chosen) {
     ctx.warnings.push({ step: index, code: "no-locator", message: "No locator was captured for this element." });
-    return `page.locator(${quote2("/* no locator captured */")})`;
+    return `${ctx.page}.locator(${quote2("/* no locator captured */")})`;
   }
   if (chosen.level === "brittle") {
     ctx.warnings.push({
@@ -1576,7 +1776,7 @@ function locatorForStep(step, index, ctx) {
       message: `The best locator captured for this element is brittle: ${chosen.text}`
     });
   }
-  return `page.${chosen.text}`;
+  return `${ctx.page}.${chosen.text}`;
 }
 function renderAssertStep(step, index, ctx) {
   const assertion = step.action === "assertVisible" ? null : step.assertion;
@@ -1601,7 +1801,7 @@ function renderAssertStep(step, index, ctx) {
     }
     arg = quote2(matcher === "toHaveURL" ? urlForCode(assertion.expected, ctx) : assertion.expected);
   }
-  const subject = matcher === "toHaveURL" ? "page" : locatorForStep(step, index, ctx);
+  const subject = matcher === "toHaveURL" ? ctx.page : locatorForStep(step, index, ctx);
   let line = `  await expect(${subject})${not}.${matcher}(${arg});`;
   if (assertion?.actual != null && assertion.actual !== assertion.expected) {
     line += ` // recorded: ${quote2(assertion.actual)}`;
@@ -1613,9 +1813,12 @@ function fileNames(value) {
   return (value ?? "").split("\n").map((name) => name.trim().replace(/^.*[\\/]/, "")).filter(Boolean);
 }
 function renderRawStep(step, index, ctx) {
-  if (step.action === "goto") return [`  await page.goto(${quote2(urlForCode(step.value ?? step.pageUrl, ctx))});`];
+  const { page } = ctx;
+  if (step.action === "goto") return [`  await ${page}.goto(${quote2(urlForCode(step.value ?? step.pageUrl, ctx))});`];
   if (step.action === "assert" || step.action === "assertVisible") return renderAssertStep(step, index, ctx);
-  if (step.action === "press" && !step.target) return [`  await page.keyboard.press(${quote2(step.value ?? "Enter")});`];
+  if (step.action === "press" && !step.target) {
+    return [`  await ${page}.keyboard.press(${quote2(step.value ?? "Enter")});`];
+  }
   const loc = locatorForStep(step, index, ctx);
   switch (step.action) {
     case "click":
@@ -1641,19 +1844,7 @@ function renderRawStep(step, index, ctx) {
     case "hover":
       return [`  await ${loc}.hover();`];
     case "fill": {
-      if (step.redacted || ctx.options.values === "env") {
-        const envVar = `PIWI_TEST_VALUE_${index}`;
-        ctx.envNames.push(envVar);
-        if (step.redacted) {
-          ctx.warnings.push({
-            step: index,
-            code: "redacted-value",
-            detail: envVar,
-            message: `A password was typed here; the spec reads it from ${envVar}.`
-          });
-        }
-        return [`  await ${loc}.fill(process.env.${envVar} ?? '');`];
-      }
+      if (readsEnv(step, ctx)) return [`  await ${loc}.fill(process.env.${envVarFor(step, index, ctx)} ?? '');`];
       return [`  await ${loc}.fill(${quote2(step.value ?? "")});`];
     }
     case "check":
@@ -1674,16 +1865,102 @@ function callIdentifiersAreSafe(entry) {
   if (entry.importName != null && !IDENTIFIER_RE.test(entry.importName)) return false;
   return true;
 }
-function objectArgExpr(param, match) {
+var RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "implements",
+  "import",
+  "in",
+  "instanceof",
+  "interface",
+  "let",
+  "new",
+  "null",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "return",
+  "static",
+  "super",
+  "switch",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield"
+]);
+function isPageExpression(text) {
+  if (typeof text !== "string") return false;
+  const segments = text.split(".");
+  return segments.every((segment) => IDENTIFIER_RE.test(segment)) && (segments[0] === "this" || !RESERVED_WORDS.has(segments[0]));
+}
+function pageExpression(options) {
+  const page = options.page ?? "page";
+  if (!isPageExpression(page)) {
+    throw new RangeError(
+      `Not a page expression (an identifier or a member chain such as app.page): ${JSON.stringify(page)}`
+    );
+  }
+  if (options.format !== "body" && page.split(".")[0] === "this") {
+    throw new RangeError(
+      `The ${options.format ?? "file"} format takes the test's parameter from the page expression, which starts with this: ${JSON.stringify(page)}`
+    );
+  }
+  return page;
+}
+function objectArgExpr(param, match, envArgs) {
   const entries = (param.fields ?? []).map((field) => {
-    const raw = match.args[`${param.name}.${field}`];
-    return raw == null ? null : `${IDENTIFIER_RE.test(field) ? field : quote2(field)}: ${quote2(raw)}`;
+    const key = `${param.name}.${field}`;
+    const env = envArgs.get(key);
+    const raw = match.args[key];
+    if (env == null && raw == null) return null;
+    return `${IDENTIFIER_RE.test(field) ? field : quote2(field)}: ${env ?? quote2(raw)}`;
   }).filter((pair) => pair != null);
   return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
 }
-function argExpr(entry, match) {
+function envArgsOf(match, steps, ctx) {
+  const envArgs = /* @__PURE__ */ new Map();
+  const params = new Map(match.entry.params.map((p) => [p.name, p]));
+  const sources = match.entry.paramSources.filter((source) => source.from === "value").sort((a, b) => a.stepIndex - b.stepIndex);
+  for (const source of sources) {
+    const type = params.get(source.param)?.type;
+    if (source.path ? type !== "object" : type !== "string") continue;
+    const index = match.matchedIndices[source.stepIndex];
+    const step = index == null ? void 0 : steps[index];
+    if (index == null || !step || !readsEnv(step, ctx)) continue;
+    const key = source.path ? `${source.param}.${source.path}` : source.param;
+    if (!envArgs.has(key)) envArgs.set(key, `process.env.${envVarFor(step, index, ctx)} ?? ''`);
+  }
+  return envArgs;
+}
+function argExpr(entry, match, envArgs) {
   return entry.params.map((p) => {
-    if (p.type === "object") return objectArgExpr(p, match);
+    if (p.type === "object") return objectArgExpr(p, match, envArgs);
+    const env = envArgs.get(p.name);
+    if (env != null) return env;
     const raw = match.args[p.name];
     if (raw == null) return p.type === "number" ? "0" : p.type === "boolean" ? "false" : "''";
     if (p.type === "number") return String(Number(raw) || 0);
@@ -1691,19 +1968,20 @@ function argExpr(entry, match) {
     return quote2(raw);
   }).join(", ");
 }
-function renderFunctionCall(match) {
+function renderFunctionCall(match, page, envArgs) {
   const { entry } = match;
-  const args = argExpr(entry, match);
+  const args = argExpr(entry, match, envArgs);
   if (entry.kind === "page-object-method" && entry.receiver) {
     return `  await ${entry.receiver}.${entry.name}(${args});`;
   }
-  return `  await ${entry.name}(page${args ? `, ${args}` : ""});`;
+  return `  await ${entry.name}(${page}${args ? `, ${args}` : ""});`;
 }
-function renderImports(usedEntries) {
+function renderImports(usedEntries, given) {
   const lines = [];
   const seenModules = /* @__PURE__ */ new Set();
   for (const entry of usedEntries) {
     if (entry.kind === "page-object-method" && entry.receiver && entry.importName) {
+      if (given.has(entry.receiver)) continue;
       const moduleKey = `${entry.module}#${entry.importName}`;
       if (!seenModules.has(moduleKey)) {
         seenModules.add(moduleKey);
@@ -1716,14 +1994,14 @@ function renderImports(usedEntries) {
   }
   return lines;
 }
-function renderInstantiations(usedEntries) {
-  const seen = /* @__PURE__ */ new Set();
+function renderInstantiations(usedEntries, page, declared) {
+  const seen = new Set(declared);
   const lines = [];
   for (const entry of usedEntries) {
     if (entry.kind !== "page-object-method" || !entry.receiver || !entry.importName) continue;
     if (seen.has(entry.receiver)) continue;
     seen.add(entry.receiver);
-    lines.push(`  const ${entry.receiver} = new ${entry.importName}(page);`);
+    lines.push(`  const ${entry.receiver} = new ${entry.importName}(${page});`);
   }
   return lines;
 }
@@ -1752,10 +2030,35 @@ function samePage(a, b) {
   const kb = pageKey(b);
   return ka === null || kb === null || ka === kb;
 }
-function viewportLine(viewport) {
-  return `  await page.setViewportSize({ width: ${Math.round(viewport.width)}, height: ${Math.round(viewport.height)} });`;
+function viewportLine(viewport, page) {
+  return `  await ${page}.setViewportSize({ width: ${Math.round(viewport.width)}, height: ${Math.round(viewport.height)} });`;
+}
+function pageStepTitle(url, origin) {
+  if (url.startsWith("/")) return url.split(/[?#]/)[0] || "/";
+  try {
+    const parsed = new URL(url);
+    return parsed.origin === origin ? parsed.pathname : `${parsed.host}${parsed.pathname}`;
+  } catch {
+    return url;
+  }
+}
+function wrapInPageSteps(lines, starts, origin) {
+  if (starts.length === 0) return { lines, at: (index) => index };
+  const out = lines.slice(0, starts[0].line);
+  starts.forEach((start, n) => {
+    const end = starts[n + 1]?.line ?? lines.length;
+    out.push(`  await test.step(${quote2(pageStepTitle(start.url, origin))}, async () => {`);
+    out.push(...lines.slice(start.line, end).map((line) => `  ${line}`));
+    out.push("  });");
+  });
+  const at = (index) => {
+    const opened = starts.filter((start) => start.line <= index).length;
+    return opened === 0 ? index : index + 2 * opened - 1;
+  };
+  return { lines: out, at };
 }
 function renderSpec(session, options = {}) {
+  const page = pageExpression(options);
   const { steps } = session;
   const viewportAt = new Map((session.viewports ?? []).map((v) => [v.step, v]));
   const title = options.title ?? "recorded flow";
@@ -1763,6 +2066,7 @@ function renderSpec(session, options = {}) {
   const ctx = {
     options,
     origin: originOf(session.startUrl) ?? originOf(steps[0]?.pageUrl ?? ""),
+    page,
     warnings: [],
     envNames: []
   };
@@ -1770,23 +2074,41 @@ function renderSpec(session, options = {}) {
   const matchedSpans = [];
   const usedEntries = [];
   const stepStarts = [];
+  const pageStarts = [];
+  const enterPageOf = (index) => {
+    const url = steps[index]?.pageUrl;
+    if (options.testSteps !== "page" || url == null) return;
+    const last = pageStarts[pageStarts.length - 1];
+    if (!last || !samePage(last.url, url)) pageStarts.push({ line: bodyLines.length, url });
+  };
   const checkNextPage = (last) => {
     if (!options.urlChecks) return;
     const next = steps[last + 1];
     const current = steps[last];
     if (!next || !current || next.action === "goto" || samePage(current.pageUrl, next.pageUrl)) return;
     const pattern = pageUrlPattern(next.pageUrl);
-    if (pattern) bodyLines.push(`  await expect(page).toHaveURL(${pattern});`);
+    enterPageOf(last + 1);
+    if (pattern) bodyLines.push(`  await expect(${page}).toHaveURL(${pattern});`);
     const acts = next.action !== "assert" && next.action !== "assertVisible";
     const chosen = acts && next.target ? chooseLocator(next.target, options) : null;
-    if (chosen) bodyLines.push(`  await expect(page.${chosen.text}).toHaveCount(1);`);
+    if (chosen) bodyLines.push(`  await expect(${page}.${chosen.text}).toHaveCount(1);`);
+  };
+  const calls = /* @__PURE__ */ new Map();
+  const callAt = (at) => {
+    if (calls.has(at)) return calls.get(at);
+    const step = steps[at];
+    const found = step && step.action !== "goto" && catalog.length > 0 ? matchFunctionAt(steps, at, catalog) : null;
+    const match = found && ![...viewportAt.keys()].some((v) => v > at && v <= Math.max(...found.matchedIndices)) ? found : null;
+    calls.set(at, match);
+    return match;
   };
   let pos = 0;
   let sawGoto = false;
   while (pos < steps.length) {
     const step = steps[pos];
+    enterPageOf(pos);
     const viewport = pos > 0 ? viewportAt.get(pos) : void 0;
-    if (viewport) bodyLines.push(viewportLine(viewport));
+    if (viewport) bodyLines.push(viewportLine(viewport, page));
     stepStarts[pos] = bodyLines.length;
     if (step.action === "goto") {
       bodyLines.push(...renderRawStep(step, pos, ctx));
@@ -1794,47 +2116,65 @@ function renderSpec(session, options = {}) {
       pos++;
       continue;
     }
-    const found = catalog.length > 0 ? matchFunctionAt(steps, pos, catalog) : null;
-    const match = found && ![...viewportAt.keys()].some((at) => at > pos && at <= Math.max(...found.matchedIndices)) ? found : null;
+    const match = callAt(pos);
     if (match) {
-      bodyLines.push(renderFunctionCall(match));
+      bodyLines.push(renderFunctionCall(match, page, envArgsOf(match, steps, ctx)));
       usedEntries.push(match.entry);
       const last = Math.max(...match.matchedIndices);
       for (let i = pos + 1; i <= last; i++) stepStarts[i] = stepStarts[pos];
       matchedSpans.push({ startStep: pos, endStep: last, functionName: match.entry.name });
-      checkNextPage(last);
       pos = last + 1;
       continue;
     }
     bodyLines.push(...renderRawStep(step, pos, ctx));
-    checkNextPage(pos);
+    if (!callAt(pos + 1)) checkNextPage(pos);
     pos++;
   }
   const start = viewportAt.get(0);
   const opening = [
-    ...start ? [viewportLine(start)] : [],
-    ...!sawGoto && session.startUrl ? [`  await page.goto(${quote2(urlForCode(session.startUrl, ctx))});`] : []
+    ...start ? [viewportLine(start, page)] : [],
+    ...!sawGoto && session.startUrl ? [`  await ${page}.goto(${quote2(urlForCode(session.startUrl, ctx))});`] : []
   ];
   bodyLines.unshift(...opening);
   const bodyOffset = opening.length;
-  const importLines = renderImports(usedEntries);
-  const instantiationLines = renderInstantiations(usedEntries);
+  const wrapped = wrapInPageSteps(
+    bodyLines,
+    pageStarts.map((start2, n) => ({ line: n === 0 ? 0 : start2.line + bodyOffset, url: start2.url })),
+    ctx.origin
+  );
+  const fixtureReceivers = options.format === "body" ? [] : [
+    ...new Set(
+      usedEntries.flatMap(
+        (e) => e.kind === "page-object-method" && e.receiver && options.fixtures?.has(e.receiver) ? [e.receiver] : []
+      )
+    )
+  ];
+  const given = /* @__PURE__ */ new Set([...options.declaredNames ?? [], ...fixtureReceivers]);
+  const importLines = renderImports(usedEntries, given);
+  const instantiationLines = renderInstantiations(usedEntries, page, given);
   const failLine = expectFailLine(options);
   const envLines = options.values === "env" && ctx.envNames.length > 0 ? [`  // Typed values come from ${[...new Set(ctx.envNames)].join(", ")}.`] : [];
-  const testBody = [...failLine ? [failLine] : [], ...envLines, ...instantiationLines, ...bodyLines];
-  const bodyStart = testBody.length - bodyLines.length + bodyOffset;
-  const linesFrom = (first) => steps.map((_, i) => first + bodyStart + (stepStarts[i] ?? 0) + 1);
+  const testBody = [...failLine ? [failLine] : [], ...envLines, ...instantiationLines, ...wrapped.lines];
+  const bodyStart = testBody.length - wrapped.lines.length;
+  const result = (lines2, header) => ({
+    code: lines2.join("\n"),
+    imports: importLines,
+    matchedSpans,
+    warnings: ctx.warnings,
+    stepLines: steps.map((_, i) => header + bodyStart + wrapped.at(bodyOffset + (stepStarts[i] ?? 0)) + 1)
+  });
+  const needsLines = (indent) => options.bodyImports === "none" ? [] : importLines.map((line) => `${indent}// Needs: ${line}`);
   if (options.format === "body") {
-    const needs = importLines.map((line) => `  // Needs: ${line}`);
-    return {
-      code: [...needs, ...testBody, ""].join("\n"),
-      matchedSpans,
-      warnings: ctx.warnings,
-      stepLines: linesFrom(needs.length)
-    };
+    const needs = needsLines("  ");
+    return result([...needs, ...testBody, ""], needs.length);
   }
   const details = renderDetails(options);
-  const testOpening = details.length > 0 ? [`test(${quote2(title)}, {`, ...details, `}, async ({ page }) => {`] : [`test(${quote2(title)}, async ({ page }) => {`];
+  const fixture = [.../* @__PURE__ */ new Set([page.split(".")[0], ...fixtureReceivers])].join(", ");
+  const testOpening = details.length > 0 ? [`test(${quote2(title)}, {`, ...details, `}, async ({ ${fixture} }) => {`] : [`test(${quote2(title)}, async ({ ${fixture} }) => {`];
+  if (options.format === "test") {
+    const needs = needsLines("");
+    return result([...needs, ...testOpening, ...testBody, `});`, ``], needs.length + testOpening.length);
+  }
   const lines = [
     // Package name interpolated rather than adjoining the preceding keyword
     // directly, so this generated-code line does not itself look like a real
@@ -1847,8 +2187,7 @@ function renderSpec(session, options = {}) {
     `});`,
     ``
   ];
-  const header = 1 + importLines.length + 1 + testOpening.length;
-  return { code: lines.join("\n"), matchedSpans, warnings: ctx.warnings, stepLines: linesFrom(header) };
+  return result(lines, 1 + importLines.length + 1 + testOpening.length);
 }
 
 // ../core/src/steps.ts
@@ -2231,7 +2570,7 @@ Code:
   --test-import <mod>   Module test and expect come from (default @playwright/test)
   --absolute-urls       Keep recorded URLs instead of paths for your baseURL
   --no-url-checks       Do not wait for each new page's URL
-  --env-values          Read typed values from PIWI_TEST_VALUE_<n> variables
+  --env-values          Read typed values from variables named after their fields (E2E_EMAIL)
   --fail                Mark the test as expected to fail (test.fail())
   --fail-reason <text>  The reason written beside test.fail()
   --tag <tag>           Add a tag; repeat for more
@@ -2391,8 +2730,8 @@ ${USAGE3}`);
     }
   } else {
     try {
-      if (fs4.statSync(args.file).size > MAX_STEPS_FILE_BYTES) throw new Error("is too large to be a steps file");
-      text = fs4.readFileSync(args.file, "utf-8");
+      if (fs5.statSync(args.file).size > MAX_STEPS_FILE_BYTES) throw new Error("is too large to be a steps file");
+      text = fs5.readFileSync(args.file, "utf-8");
     } catch (e) {
       const reason = e.code === "ENOENT" ? "does not exist" : e.message;
       console.error(`piwi codegen: ${args.file} ${reason}`);
@@ -2424,8 +2763,8 @@ ${USAGE3}`);
     return EXIT_OK3;
   }
   try {
-    fs4.mkdirSync(path7.dirname(args.out), { recursive: true });
-    fs4.writeFileSync(args.out, result.code, { flag: args.force ? "w" : "wx" });
+    fs5.mkdirSync(path8.dirname(args.out), { recursive: true });
+    fs5.writeFileSync(args.out, result.code, { flag: args.force ? "w" : "wx" });
   } catch (e) {
     const exists = e.code === "EEXIST";
     console.error(`piwi codegen: ${exists ? `${args.out} exists \u2014 pass --force to replace it` : e.message}`);
@@ -2477,148 +2816,6 @@ function estimateFlakeSessionMs(arms, medianDurationMs) {
   return total;
 }
 
-// src/internal/config/desktop.ts
-var fs5 = __toESM(require("fs"));
-var os = __toESM(require("os"));
-var path8 = __toESM(require("path"));
-function defaultDesktopConfigPath() {
-  return path8.join(os.homedir(), ".piwi", "desktop.json");
-}
-function readDesktopConfig(filePath) {
-  try {
-    const parsed = JSON.parse(fs5.readFileSync(filePath, "utf8"));
-    const url = parsed?.url;
-    const token = parsed?.token;
-    if (typeof url !== "string" || !url) return null;
-    if (typeof token !== "string" || !token) return null;
-    return { url, token };
-  } catch {
-    return null;
-  }
-}
-
-// src/internal/config/env.ts
-var DEFAULTS = {
-  projectName: "default-project",
-  uploadTraces: true,
-  uploadReport: true,
-  liveFileUploads: true,
-  collectScmInfo: true,
-  collectCiInfo: true,
-  collectPerformanceMetrics: true,
-  captureLocators: true,
-  capturePageState: true,
-  // Off by default: the page inventory reads control and link names from every
-  // visited page, so it stays opt-in until a project turns it on.
-  capturePageInventory: false,
-  // Off by default: JavaScript coverage slows the page, so a scheduled job opts in.
-  captureCodeReach: false,
-  captureServerTraces: true,
-  captureResources: true,
-  leakCheck: "report",
-  sampleAriaOnPass: true,
-  uploadManifest: true,
-  defaultCapture: true,
-  streaming: true,
-  streamingBatchSize: 5,
-  streamingBatchDelay: 2e3,
-  maxStreamBufferBytes: 100 * 1024 * 1024,
-  submitTimeout: 15 * 60 * 1e3,
-  failOnFlakyTests: false,
-  username: null,
-  password: null,
-  apiKey: null,
-  verbose: false
-};
-var PIWI_ENV_KEYS = {
-  serverUrl: "PIWI_DASHBOARD_URL",
-  projectName: "PIWI_PROJECT_NAME",
-  verbose: "PIWI_VERBOSE",
-  apiKey: "PIWI_API_KEY",
-  username: "PIWI_USERNAME",
-  password: "PIWI_PASSWORD",
-  environment: "PIWI_ENVIRONMENT",
-  label: "PIWI_LABEL",
-  runLabel: "PIWI_RUN_LABEL",
-  keep: "PIWI_KEEP",
-  streaming: "PIWI_STREAMING",
-  streamingBatchSize: "PIWI_STREAMING_BATCH_SIZE",
-  streamingBatchDelay: "PIWI_STREAMING_BATCH_DELAY",
-  maxStreamBufferBytes: "PIWI_MAX_STREAM_BUFFER_BYTES",
-  submitTimeout: "PIWI_SUBMIT_TIMEOUT",
-  liveFileUploads: "PIWI_LIVE_FILE_UPLOADS",
-  failOnFlakyTests: "PIWI_FAIL_ON_FLAKY_TESTS",
-  uploadTraces: "PIWI_UPLOAD_TRACES",
-  uploadReport: "PIWI_UPLOAD_REPORT",
-  captureLocators: "PIWI_CAPTURE_LOCATORS",
-  capturePageState: "PIWI_CAPTURE_PAGE_STATE",
-  capturePageInventory: "PIWI_CAPTURE_PAGE_INVENTORY",
-  captureCodeReach: "PIWI_CAPTURE_CODE_REACH",
-  codeReachRoots: "PIWI_CODE_REACH_ROOTS",
-  captureServerTraces: "PIWI_CAPTURE_SERVER_TRACES",
-  captureResources: "PIWI_CAPTURE_RESOURCES",
-  leakCheck: "PIWI_LEAK_CHECK",
-  sampleAriaOnPass: "PIWI_SAMPLE_ARIA_ON_PASS",
-  uploadManifest: "PIWI_UPLOAD_MANIFEST",
-  defaultCapture: "PIWI_DEFAULT_CAPTURE",
-  inspectOnFailure: "PIWI_INSPECT_ON_FAIL",
-  pickLocatorOnFailure: "PIWI_PICK_LOCATOR_ON_FAIL",
-  outputFile: "PIWI_OUTPUT_FILE",
-  aiMode: "PIWI_AI",
-  aiDir: "PIWI_AI_DIR",
-  aiOnMiss: "PIWI_AI_ON_MISS",
-  aiMaxSteps: "PIWI_AI_MAX_FLOW_STEPS",
-  aiMaxSnapshotChars: "PIWI_AI_MAX_SNAPSHOT_CHARS",
-  aiOptionalProbeTimeout: "PIWI_AI_OPTIONAL_PROBE_TIMEOUT",
-  aiResponseWaitTimeout: "PIWI_AI_RESPONSE_WAIT_TIMEOUT",
-  aiScreenshotFallback: "PIWI_AI_SCREENSHOT_FALLBACK"
-};
-var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
-var PIWI_SHARD_ENV = "PIWI_SHARD";
-var PIWI_PROBE_ENV = {
-  flag: "PIWI_PROBE",
-  plan: "PIWI_PROBE_PLAN",
-  results: "PIWI_PROBE_RESULTS",
-  secret: "PIWI_PROBE_SECRET"
-};
-var PIWI_FLAKE_ENV = {
-  plan: "PIWI_FLAKE_PLAN",
-  results: "PIWI_FLAKE_RESULTS"
-};
-var ENV_FALLBACK_SPECS = [
-  { option: "serverUrl", env: PIWI_ENV_KEYS.serverUrl, kind: "string" },
-  { option: "projectName", env: PIWI_ENV_KEYS.projectName, kind: "string" },
-  { option: "apiKey", env: PIWI_ENV_KEYS.apiKey, kind: "string" },
-  { option: "username", env: PIWI_ENV_KEYS.username, kind: "string" },
-  { option: "password", env: PIWI_ENV_KEYS.password, kind: "string" },
-  { option: "environment", env: PIWI_ENV_KEYS.environment, kind: "string" },
-  { option: "label", env: PIWI_ENV_KEYS.label, kind: "string" },
-  { option: "runLabel", env: PIWI_ENV_KEYS.runLabel, kind: "string" },
-  { option: "keep", env: PIWI_ENV_KEYS.keep, kind: "bool" },
-  { option: "streaming", env: PIWI_ENV_KEYS.streaming, kind: "bool" },
-  { option: "streamingBatchSize", env: PIWI_ENV_KEYS.streamingBatchSize, kind: "number" },
-  { option: "streamingBatchDelay", env: PIWI_ENV_KEYS.streamingBatchDelay, kind: "number" },
-  { option: "maxStreamBufferBytes", env: PIWI_ENV_KEYS.maxStreamBufferBytes, kind: "number" },
-  { option: "submitTimeout", env: PIWI_ENV_KEYS.submitTimeout, kind: "number" },
-  { option: "liveFileUploads", env: PIWI_ENV_KEYS.liveFileUploads, kind: "bool" },
-  { option: "failOnFlakyTests", env: PIWI_ENV_KEYS.failOnFlakyTests, kind: "bool" },
-  { option: "uploadTraces", env: PIWI_ENV_KEYS.uploadTraces, kind: "bool" },
-  { option: "uploadReport", env: PIWI_ENV_KEYS.uploadReport, kind: "bool" },
-  { option: "captureLocators", env: PIWI_ENV_KEYS.captureLocators, kind: "bool" },
-  { option: "capturePageState", env: PIWI_ENV_KEYS.capturePageState, kind: "bool" },
-  { option: "capturePageInventory", env: PIWI_ENV_KEYS.capturePageInventory, kind: "bool" },
-  { option: "captureCodeReach", env: PIWI_ENV_KEYS.captureCodeReach, kind: "bool" },
-  { option: "captureServerTraces", env: PIWI_ENV_KEYS.captureServerTraces, kind: "bool" },
-  { option: "captureResources", env: PIWI_ENV_KEYS.captureResources, kind: "bool" },
-  { option: "leakCheck", env: PIWI_ENV_KEYS.leakCheck, kind: "string" },
-  { option: "sampleAriaOnPass", env: PIWI_ENV_KEYS.sampleAriaOnPass, kind: "bool" },
-  { option: "uploadManifest", env: PIWI_ENV_KEYS.uploadManifest, kind: "bool" },
-  { option: "defaultCapture", env: PIWI_ENV_KEYS.defaultCapture, kind: "bool" },
-  { option: "inspectOnFailure", env: PIWI_ENV_KEYS.inspectOnFailure, kind: "bool" },
-  { option: "pickLocatorOnFailure", env: PIWI_ENV_KEYS.pickLocatorOnFailure, kind: "bool" },
-  { option: "outputFile", env: PIWI_ENV_KEYS.outputFile, kind: "string" }
-];
-
 // ../core/src/flake-verdict.ts
 var FLAKE_SIGNIFICANCE = 0.05;
 var FLAKE_REPRODUCED_RATE = 0.5;
@@ -3462,7 +3659,7 @@ var fs9 = __toESM(require("fs"));
 function formatGateResult(result) {
   const { facts } = result;
   const lines = [
-    result.passed ? `\u2714 Piwi gate passed \u2014 ${facts.projectName} run #${facts.runId}` : `\u2716 Piwi gate failed \u2014 ${facts.projectName} run #${facts.runId}`,
+    result.verdict === "inconclusive" ? `? Piwi gate inconclusive \u2014 ${facts.projectName} run #${facts.runId}` : result.passed ? `\u2714 Piwi gate passed \u2014 ${facts.projectName} run #${facts.runId}` : `\u2716 Piwi gate failed \u2014 ${facts.projectName} run #${facts.runId}`,
     `  ${facts.totalTests} tests, ${facts.failedTests} failed, ${facts.newRegressions} new, ${facts.newFlaky} newly flaky, ${facts.flakyTests} flaky`
   ];
   if (facts.quarantinedFailures > 0) {
@@ -3474,6 +3671,10 @@ function formatGateResult(result) {
     const { leaks, newLeaks } = facts.resources;
     lines.push(`  ${leaks.length} ${leaks.length === 1 ? "leak" : "leaks"}, ${newLeaks.length} new`);
   }
+  if (facts.incident) {
+    lines.push(`  ? The run is an environment incident: ${facts.incident.reason}`);
+    lines.push("  Re-run once the environment is back, or clear the flag on the run page if it is wrong.");
+  }
   for (const violation of result.violations) lines.push(`  \u2716 ${violation.message}`);
   for (const warning of result.warnings ?? []) lines.push(`  \u26A0 ${warning}`);
   lines.push(`  ${facts.runUrl}`);
@@ -3484,6 +3685,7 @@ function formatGateResult(result) {
 var EXIT_OK4 = 0;
 var EXIT_VIOLATED = 1;
 var EXIT_ERROR5 = 2;
+var EXIT_INCONCLUSIVE = 3;
 var USAGE5 = `
 piwi gate \u2014 fail a CI job on the dashboard's analysis of a run
 
@@ -3519,7 +3721,7 @@ Other:
   --json                   Print the raw result as JSON instead of a summary
   -h, --help               Show this help
 
-Exit codes: 0 satisfied, 1 violated, 2 could not evaluate.
+Exit codes: 0 satisfied, 1 violated, 2 could not evaluate, 3 inconclusive (an environment incident).
 `.trim();
 function readOption4(argv, name) {
   const withEquals = argv.find((arg) => arg.startsWith(`${name}=`));
@@ -3580,7 +3782,7 @@ function parseGateArgs(argv, env) {
   };
 }
 async function requestGate(args) {
-  const headers = { "Content-Type": "application/json" };
+  const headers = { "Content-Type": "application/json", "X-Piwi-Client": "cli" };
   if (args.apiKey) headers["X-API-Key"] = args.apiKey;
   const res = await fetch(`${args.serverUrl}/api/test-runs/${args.runId}/gate`, {
     method: "POST",
@@ -3619,6 +3821,7 @@ async function runGate(argv, env = process.env) {
   } else {
     console.log(formatGateResult(result));
   }
+  if (result.verdict === "inconclusive") return EXIT_INCONCLUSIVE;
   return result.passed ? EXIT_OK4 : EXIT_VIOLATED;
 }
 
@@ -3840,6 +4043,58 @@ function ensureGitignoreEntry(existing, entry = ".env") {
 // src/cli/skills.ts
 var fs11 = __toESM(require("fs"));
 var path13 = __toESM(require("path"));
+
+// ../core/src/skill-stamp.ts
+var SKILL_VERSION_KEY = "piwi-version";
+var SKILL_HASH_KEY = "piwi-hash";
+var FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+function fnv32(input, seed) {
+  let h = seed >>> 0;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function hash16(input) {
+  return fnv32(input, 2166136261) + fnv32(input, 16777619);
+}
+function withoutHashLine(markdown) {
+  return markdown.replace(new RegExp(`^${SKILL_HASH_KEY}:.*\\r?\\n`, "m"), "");
+}
+function skillContentHash(markdown) {
+  return hash16(withoutHashLine(markdown).replace(/\r\n/g, "\n"));
+}
+function stampSkill(template, version) {
+  const match = FRONT_MATTER.exec(template);
+  if (!match) return template;
+  const front = match[1].split(/\r?\n/).filter((line) => !line.startsWith(`${SKILL_VERSION_KEY}:`) && !line.startsWith(`${SKILL_HASH_KEY}:`));
+  const versionLine = `${SKILL_VERSION_KEY}: ${version}`;
+  const versioned = template.replace(match[0], () => `---
+${[...front, versionLine].join("\n")}
+---`);
+  const hash = skillContentHash(versioned);
+  return versioned.replace(`${versionLine}
+---`, () => `${versionLine}
+${SKILL_HASH_KEY}: ${hash}
+---`);
+}
+function readSkillStamp(markdown) {
+  const lines = FRONT_MATTER.exec(markdown)?.[1]?.split(/\r?\n/) ?? [];
+  const read = (key) => {
+    const line = lines.find((l) => l.startsWith(`${key}:`));
+    return line ? line.slice(key.length + 1).trim() || null : null;
+  };
+  return { version: read(SKILL_VERSION_KEY), hash: read(SKILL_HASH_KEY) };
+}
+function classifyInstalledSkill(installed, stamped) {
+  if (installed.replace(/\r\n/g, "\n") === stamped.replace(/\r\n/g, "\n")) return "current";
+  const stamp = readSkillStamp(installed);
+  if (!stamp.hash) return "unstamped";
+  return skillContentHash(installed) === stamp.hash ? "outdated" : "edited";
+}
+
+// src/cli/skills.ts
 var SETUP_SKILL = "setup-piwi";
 var WORKFLOW_SKILLS = [
   "investigate-failure",
@@ -3871,6 +4126,14 @@ function readFrontMatter(markdown) {
   }
   return out;
 }
+function readTemplatesVersion(templatesDir) {
+  try {
+    const pkg = JSON.parse(fs11.readFileSync(path13.join(templatesDir, "..", "package.json"), "utf-8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 function templatePath(templatesDir, slug) {
   return path13.join(templatesDir, "skills", slug, "SKILL.md");
 }
@@ -3895,23 +4158,37 @@ function installSkills(opts) {
       results.push({ step, status: "error", detail: `no template found for "${slug}"` });
       continue;
     }
-    const contents = fs11.readFileSync(source, "utf-8");
+    const version = opts.version ?? readTemplatesVersion(opts.templatesDir);
+    const contents = stampSkill(fs11.readFileSync(source, "utf-8"), version);
     const exists = fs11.existsSync(dest);
-    if (exists && !opts.force) {
-      const identical = fs11.readFileSync(dest, "utf-8") === contents;
-      results.push({
-        step,
-        file: relDest,
-        status: identical ? "already" : "skipped",
-        detail: identical ? "skill already installed" : "skill exists and differs \u2014 pass --force to overwrite"
-      });
-      continue;
+    let detail = "installed skill";
+    if (exists) {
+      const installed = fs11.readFileSync(dest, "utf-8");
+      const state = classifyInstalledSkill(installed, contents);
+      const from = readSkillStamp(installed).version;
+      if (state === "current") {
+        results.push({ step, file: relDest, status: "already", detail: `skill already installed (${version})` });
+        continue;
+      }
+      if (state === "outdated") {
+        detail = `outdated (${from ?? "unknown version"}) \u2014 updated to ${version}`;
+      } else if (!opts.force) {
+        results.push({
+          step,
+          file: relDest,
+          status: "skipped",
+          detail: state === "edited" ? `edited since ${from ?? "it was"} installed \u2014 pass --force to replace it with ${version}` : `skill exists and differs \u2014 pass --force to replace it with ${version}`
+        });
+        continue;
+      } else {
+        detail = state === "edited" ? `edited \u2014 replaced with ${version}` : `replaced with ${version}`;
+      }
     }
     if (!opts.dryRun) {
       fs11.mkdirSync(path13.dirname(dest), { recursive: true });
       fs11.writeFileSync(dest, contents);
     }
-    results.push({ step, file: relDest, status: exists ? "updated" : "created", detail: "installed skill" });
+    results.push({ step, file: relDest, status: exists ? "updated" : "created", detail });
   }
   return results;
 }
@@ -3929,7 +4206,8 @@ Commands:
 Options for "add":
   --dir <path>      Directory to install into (default: ${DEFAULT_SKILLS_DIR})
   --cwd <path>      Project root to operate on (default: current directory)
-  --force           Overwrite a skill file that already exists
+  --force           Replace a skill that was edited since it was installed
+                    (an untouched skill from an older release is always updated)
   --dry-run         Report what would be written without writing
   --json            Print the results as JSON
 
@@ -4617,7 +4895,7 @@ async function runRunImpact(args, env) {
   printWarnings(impact);
   if (impact.impact.widened) {
     console.error(
-      `piwi run: impact widened to the full suite (${impact.impact.unmappedSourceFiles.length} unmapped source file(s))`
+      `piwi run: impact widened to the full suite (${impact.impact.unmappedSourceFiles.length} changed file(s) not fully mapped to tests)`
     );
     return spawnPlaywrightForRun(args.pkgRunner, args.extra, env);
   }
@@ -5966,7 +6244,10 @@ async function runPreflight(argv, env = process.env, cwd = process.cwd()) {
       console.error("piwi preflight: no test reaches this change \u2014 nothing to run");
       return code;
     }
-    const runCode = await spawnPlaywrightForRun(args.pkgRunner, [...runArgs, ...args.extra], env);
+    const runCode = await spawnPlaywrightForRun(args.pkgRunner, [...runArgs, ...args.extra], {
+      ...env,
+      ...originEnv("preflight")
+    });
     if (runCode !== 0) code = EXIT_BREAKS;
   }
   return code;