@piwitests/reporter 0.24.0 → 0.26.0

package/README.md

@@ -1,8 +1,8 @@
 # Piwi Dashboard Reporter
 
-A custom Playwright reporter that sends test results to a [Piwi Dashboard](https://piwitests.github.io) server. It handles uploading test results, HTML reports, trace files, and performance metrics — with optional live streaming of results as tests execute.
+A custom Playwright reporter that sends test results to a [Piwi Dashboard](https://piwitests.dev) server. It handles uploading test results, HTML reports, trace files, and performance metrics — with optional live streaming of results as tests execute.
 
-📖 **[Full documentation](https://piwitests.github.io/reporter)**
+📖 **[Full documentation](https://piwitests.dev/reporter)**
 
 ## Installation
 
@@ -18,14 +18,14 @@ From your Playwright project, `npx @piwitests/reporter init` installs the report
 npx @piwitests/reporter init --server-url http://localhost:3000 --project my-project
 ```
 
-Every step is idempotent (safe to re-run); a config shape it will not rewrite is reported as `manual` with the exact change to make, never mangled. Add `--dry-run` to preview or `--json` for a machine-readable plan an agent can act on. It also installs the [Piwi agent skills](https://piwitests.github.io/mcp#agent-skills) so your coding agent can investigate failures, heal locators, and stabilize flaky tests. Run `npx @piwitests/reporter init --help` for all options, or wire it up by hand with the steps below.
+Every step is idempotent (safe to re-run); a config shape it will not rewrite is reported as `manual` with the exact change to make, never mangled. Add `--dry-run` to preview or `--json` for a machine-readable plan an agent can act on. It also installs the [Piwi agent skills](https://piwitests.dev/mcp#agent-skills) so your coding agent can investigate failures, heal locators, and stabilize flaky tests. Run `npx @piwitests/reporter init --help` for all options, or wire it up by hand with the steps below.
 
 > The package is `@piwitests/reporter`; its command is `piwi`. Invoke it through the package name (`npx @piwitests/reporter <command>`) so npx resolves this package — `npx piwi` would fetch an unrelated `piwi` from npm. Once the reporter is a project dependency, `npx piwi <command>` resolves the local binary and works too.
 
 ## Quick start
 
 `wrapConfig` is the recommended setup. It injects the reporter **and** a global
-setup step (so the run shows up as "initialising" while your `globalSetup` runs),
+setup step (so the run shows up as "initializing" while your `globalSetup` runs),
 and forwards your options to that setup:
 
 ```typescript
@@ -184,7 +184,7 @@ Then import `test` from your fixtures file in every spec — a spec that imports
 
 Capture works for the `page` fixture, `browser.newPage()`, `browser.newContext().newPage()`, and popups. Everything is only collected when `collectPerformanceMetrics` is `true` (the default); locator snapshots can be disabled separately with `captureLocators: false`.
 
-Without the fixtures you still get full run history, statuses, errors, traces, reports, streaming, and clustering — the fixtures add the slow-endpoint, Web Vitals, console, ARIA, and locator-healing layers. See the [capture fixtures guide](https://piwitests.github.io/capture-fixtures) for the full feature matrix and composition patterns.
+Without the fixtures you still get full run history, statuses, errors, traces, reports, streaming, and clustering — the fixtures add the slow-endpoint, Web Vitals, console, ARIA, and locator-healing layers. See the [capture fixtures guide](https://piwitests.dev/capture-fixtures) for the full feature matrix and composition patterns.
 
 ## AI steps
 
@@ -204,7 +204,7 @@ export const test = extendPiwiAi(extendPiwiFixtures(base))
 
 Author missing entries once in `resolve` mode (`PIWI_AI=resolve`, pointed at a dashboard with an AI provider configured), commit the artifacts, and CI replays them offline. `{param}` placeholders are type-checked and masked out of everything sent to the model. Manage the committed entries with `piwi ai check | resolve | prune`.
 
-See the [AI steps guide](https://piwitests.github.io/ai-steps) for the authoring/replay lifecycle, the safety model (allowlisted, drift-guarded, postcondition-verified), and the full option/env-var reference.
+See the [AI steps guide](https://piwitests.dev/ai-steps) for the authoring/replay lifecycle, the safety model (allowlisted, drift-guarded, postcondition-verified), and the full option/env-var reference.
 
 ## Authentication
 
@@ -298,7 +298,7 @@ addition:
 
 ## Requirements
 
-- Node.js 18 or higher (the reporter runs inside your test project — the dashboard *server* itself targets Node 24+, or use its Docker image)
+- Node.js 18 or higher (the reporter runs inside your test project — the dashboard *server* itself targets Node 22+, or use its Docker image)
 - Playwright Test 1.40 or higher
 - Running Piwi Dashboard server
 

package/dist/cli/index.js

@@ -414,7 +414,7 @@ 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}`,
-    `  ${facts.totalTests} tests, ${facts.failedTests} failed, ${facts.newRegressions} new, ${facts.newFlaky} newly flaky`
+    `  ${facts.totalTests} tests, ${facts.failedTests} failed, ${facts.newRegressions} new, ${facts.newFlaky} newly flaky, ${facts.flakyTests} flaky`
   ];
   if (facts.quarantinedFailures > 0) {
     lines.push(
@@ -453,6 +453,8 @@ Policy (at least one is required):
   --max-new-flaky <n>      Fail when more than n tests newly became flaky
   --max-quarantined <n>    Fail when more than n tests are quarantined
   --fail-on-new-cluster    Fail when this run introduced a new failure cluster
+  --fail-on-flaky          Fail when this run contains any flaky test
+  --require-selection <key>  Fail when a test the named selection matches did not run or failed
 
 Other:
   --json                   Print the raw result as JSON instead of a summary
@@ -475,9 +477,9 @@ function readCount(argv, name) {
   if (!Number.isFinite(n) || n < 0) throw new Error(`${name} expects a non-negative number, got "${raw}"`);
   return Math.floor(n);
 }
-function readRunIdFromFile(path9) {
+function readRunIdFromFile(path10) {
   try {
-    const parsed = JSON.parse(fs3.readFileSync(path9, "utf-8"));
+    const parsed = JSON.parse(fs3.readFileSync(path10, "utf-8"));
     const runId = Number(parsed.runId);
     return Number.isFinite(runId) && runId > 0 ? runId : null;
   } catch {
@@ -504,7 +506,9 @@ function parseGateArgs(argv, env) {
     maxNewRegressions: readCount(argv, "--max-new-regressions"),
     maxNewFlaky: readCount(argv, "--max-new-flaky"),
     maxQuarantined: readCount(argv, "--max-quarantined"),
-    failOnNewCluster: argv.includes("--fail-on-new-cluster")
+    failOnNewCluster: argv.includes("--fail-on-new-cluster"),
+    failOnFlaky: argv.includes("--fail-on-flaky"),
+    requireSelection: readOption2(argv, "--require-selection")
   };
   return { serverUrl, apiKey: readOption2(argv, "--api-key") ?? env.PIWI_API_KEY ?? null, runId, policy };
 }
@@ -770,7 +774,12 @@ function ensureGitignoreEntry(existing, entry = ".env") {
 var fs5 = __toESM(require("fs"));
 var path7 = __toESM(require("path"));
 var SETUP_SKILL = "setup-piwi";
-var WORKFLOW_SKILLS = ["investigate-failure", "apply-locator-healing", "stabilize-flaky-tests"];
+var WORKFLOW_SKILLS = [
+  "investigate-failure",
+  "apply-locator-healing",
+  "stabilize-flaky-tests",
+  "run-the-right-tests"
+];
 var ALL_SKILLS = [SETUP_SKILL, ...WORKFLOW_SKILLS];
 var DEFAULT_SKILLS_DIR = path7.join(".claude", "skills");
 function findTemplatesDir(fromDir) {
@@ -1186,8 +1195,415 @@ Piwi setup${opts.dryRun ? " (dry run \u2014 nothing written)" : ""} for "${opts.
   return steps.some((s) => s.status === "error") ? 1 : 0;
 }
 
-// src/cli/index.ts
+// src/cli/select.ts
+var fs7 = __toESM(require("fs"));
+var path9 = __toESM(require("path"));
+var import_node_child_process3 = require("child_process");
+var import_node_module = require("module");
+
+// src/internal/support/selection-client.ts
+function authHeaders(apiKey) {
+  return apiKey ? { "X-API-Key": apiKey } : {};
+}
+async function resolveProjectId(options) {
+  if (!options.project) throw new Error("No project \u2014 pass --project or set PIWI_PROJECT_NAME");
+  if (/^\d+$/.test(options.project)) return Number(options.project);
+  const res = await fetch(`${options.serverUrl}/api/projects/menu`, { headers: authHeaders(options.apiKey) });
+  if (!res.ok) throw new Error(`Could not list projects (dashboard returned ${res.status})`);
+  const body = await res.json();
+  const match = body.items?.find((p) => p.name.toLowerCase() === options.project.toLowerCase());
+  if (!match) throw new Error(`No project named "${options.project}" on this dashboard`);
+  return match.id;
+}
+async function fetchResolution(options, projectId) {
+  const params = new URLSearchParams({ format: options.format ?? "args" });
+  if (options.pkgRunner) params.set("pkgRunner", options.pkgRunner);
+  if (options.budgetMs != null) params.set("budgetMs", String(options.budgetMs));
+  if (options.shard) params.set("shard", options.shard);
+  if (options.order) params.set("order", options.order);
+  const url = `${options.serverUrl}/api/projects/${projectId}/selections/${encodeURIComponent(options.key)}/resolve?${params}`;
+  const res = await fetch(url, { headers: authHeaders(options.apiKey) });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.message || `Dashboard returned ${res.status} resolving "${options.key}"`);
+  }
+  return await res.json();
+}
+async function fetchImpact(options, projectId, changedFiles) {
+  const url = `${options.serverUrl}/api/projects/${projectId}/selections/impact`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...authHeaders(options.apiKey) },
+    body: JSON.stringify({
+      changedFiles,
+      format: options.format ?? "args",
+      shard: options.shard ?? void 0,
+      order: options.order ?? void 0
+    })
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.message || `Dashboard returned ${res.status} resolving impact`);
+  }
+  return await res.json();
+}
+
+// src/cli/select.ts
+var EXIT_OK3 = 0;
+var EXIT_ERROR3 = 2;
 var USAGE5 = `
+piwi select / piwi run \u2014 run a saved selection of tests
+
+Usage:
+  npx @piwitests/reporter select <key> [options]     print the Playwright args
+  npx @piwitests/reporter run <key> [options] [-- <playwright args>]
+  npx @piwitests/reporter run impact --base <ref>    run the tests your diff impacts
+
+Connection:
+  --server-url <url>    Dashboard URL         (env PIWI_DASHBOARD_URL)
+  --api-key <key>       API key               (env PIWI_API_KEY)
+  --project <name|id>   Project               (env PIWI_PROJECT_NAME)
+
+Selection:
+  --format <fmt>        args (file:line, default) | grep | files | json
+  --budget <duration>   Cap total time, e.g. 5m, 90s, 300000 (ms)
+  --shard <i/n>         Keep only shard i of n, balanced by test duration
+  --fail-fast           Order the least-reliable tests first (fail-fast)
+  --base <ref>          For "impact": the ref to diff the working tree against
+
+Behavior:
+  --strict              Fail (exit 2) instead of falling back when unreachable
+  --pkg-runner <cmd>    Package runner for the printed command (default npx)
+  --json                Print the full resolution as JSON (select only)
+  -h, --help            Show this help
+
+Exit codes: 0 ok, 1 the test run failed (run only), 2 could not resolve.
+`.trim();
+var IMPACT_KEY = "impact";
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--server-url",
+  "--api-key",
+  "--project",
+  "--format",
+  "--budget",
+  "--shard",
+  "--base",
+  "--pkg-runner"
+]);
+function readOption5(argv, name) {
+  const withEquals = argv.find((arg) => arg.startsWith(`${name}=`));
+  if (withEquals) return withEquals.slice(name.length + 1);
+  const index = argv.indexOf(name);
+  if (index === -1) return void 0;
+  const value = argv[index + 1];
+  return value && !value.startsWith("-") ? value : void 0;
+}
+function findKey(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok.startsWith("-")) {
+      if (!tok.includes("=") && VALUE_FLAGS.has(tok)) i++;
+      continue;
+    }
+    return tok;
+  }
+  return void 0;
+}
+function parseDuration(raw) {
+  const match = raw.trim().match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/);
+  if (!match) return null;
+  const value = Number(match[1]);
+  const unit = match[2];
+  const factor = unit === "h" ? 36e5 : unit === "m" ? 6e4 : unit === "s" ? 1e3 : 1;
+  const ms = Math.round(value * factor);
+  return ms > 0 ? ms : null;
+}
+function parseSelectArgs(argv, env) {
+  const dashIndex = argv.indexOf("--");
+  const own = dashIndex === -1 ? argv : argv.slice(0, dashIndex);
+  const extra = dashIndex === -1 ? [] : argv.slice(dashIndex + 1);
+  const serverUrl = (readOption5(own, "--server-url") ?? env.PIWI_DASHBOARD_URL ?? "").replace(/\/$/, "");
+  if (!serverUrl) throw new Error("No dashboard URL \u2014 pass --server-url or set PIWI_DASHBOARD_URL");
+  const key = findKey(own);
+  if (!key) throw new Error("No selection key \u2014 usage: piwi select <key>");
+  const budgetRaw = readOption5(own, "--budget");
+  let budgetMs = null;
+  if (budgetRaw !== void 0) {
+    budgetMs = parseDuration(budgetRaw);
+    if (budgetMs === null) throw new Error(`--budget expects a duration like 5m or 90s, got "${budgetRaw}"`);
+  }
+  const shard = readOption5(own, "--shard") ?? null;
+  if (shard !== null && !/^\d+\s*\/\s*\d+$/.test(shard)) {
+    throw new Error(`--shard expects an "i/n" spec like 2/4, got "${shard}"`);
+  }
+  return {
+    serverUrl,
+    apiKey: readOption5(own, "--api-key") ?? env.PIWI_API_KEY ?? null,
+    project: readOption5(own, "--project") ?? env.PIWI_PROJECT_NAME ?? "",
+    key,
+    format: readOption5(own, "--format") ?? "args",
+    budgetMs,
+    shard,
+    order: own.includes("--fail-fast") ? "failureLikelihood" : null,
+    base: readOption5(own, "--base") ?? null,
+    strict: own.includes("--strict"),
+    pkgRunner: readOption5(own, "--pkg-runner") ?? "npx",
+    json: own.includes("--json"),
+    extra
+  };
+}
+var CACHE_FILE = path9.join(".piwi", "selection-cache.json");
+function cacheKey(projectId, args) {
+  return `${projectId}:${args.key}:${args.format}:${args.budgetMs ?? 0}:${args.shard ?? ""}:${args.order ?? ""}`;
+}
+function readCache(projectId, args) {
+  try {
+    const store = JSON.parse(fs7.readFileSync(CACHE_FILE, "utf-8"));
+    return store[cacheKey(projectId, args)] ?? null;
+  } catch {
+    return null;
+  }
+}
+function writeCache(projectId, args, resolution) {
+  try {
+    let store = {};
+    try {
+      store = JSON.parse(fs7.readFileSync(CACHE_FILE, "utf-8"));
+    } catch {
+    }
+    store[cacheKey(projectId, args)] = resolution;
+    fs7.mkdirSync(path9.dirname(CACHE_FILE), { recursive: true });
+    fs7.writeFileSync(CACHE_FILE, JSON.stringify(store, null, 2));
+  } catch {
+  }
+}
+async function resolveWithCache(args, projectId) {
+  try {
+    const resolution = await fetchResolution(args, projectId);
+    writeCache(projectId, args, resolution);
+    return { resolution, fromCache: false };
+  } catch (e) {
+    if (args.strict) throw e;
+    const cached = readCache(projectId, args);
+    if (cached) {
+      console.error(`piwi: dashboard unreachable, using cached resolution \u2014 ${e.message}`);
+      return { resolution: cached, fromCache: true };
+    }
+    return null;
+  }
+}
+function printWarnings(resolution) {
+  for (const w of resolution.warnings) console.error(`piwi: warning [${w.code}] ${w.message}`);
+}
+function gitChangedFiles(base) {
+  const out = (0, import_node_child_process3.execFileSync)("git", ["diff", "--name-only", base], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  return [
+    ...new Set(
+      out.split("\n").map((line) => line.trim()).filter(Boolean)
+    )
+  ];
+}
+async function loadImpact(args, projectId) {
+  const files = gitChangedFiles(args.base);
+  return fetchImpact(args, projectId, files);
+}
+async function runSelectImpact(args) {
+  let impact;
+  try {
+    const projectId = await resolveProjectId(args);
+    impact = await loadImpact(args, projectId);
+  } catch (e) {
+    console.error(`piwi select: ${e.message}`);
+    return EXIT_ERROR3;
+  }
+  printWarnings(impact);
+  console.error(
+    `piwi select: ${impact.impact.changedFiles} changed file(s) \u2192 ${impact.estimate.count} impacted test(s)${impact.impact.widened ? " (widened to full suite)" : ""}`
+  );
+  if (args.json) {
+    console.log(JSON.stringify(impact, null, 2));
+    return EXIT_OK3;
+  }
+  console.log(impact.impact.widened ? "" : impact.materialization.args.join(" "));
+  return EXIT_OK3;
+}
+async function runSelect(argv, env = process.env) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    console.log(USAGE5);
+    return EXIT_OK3;
+  }
+  let args;
+  try {
+    args = parseSelectArgs(argv, env);
+  } catch (e) {
+    console.error(`piwi select: ${e.message}
+`);
+    console.error(USAGE5);
+    return EXIT_ERROR3;
+  }
+  if (args.key === IMPACT_KEY) {
+    if (!args.base) {
+      console.error("piwi select: impact needs a base ref \u2014 pass --base <ref> (e.g. --base origin/main)");
+      return EXIT_ERROR3;
+    }
+    return runSelectImpact(args);
+  }
+  let resolution;
+  try {
+    const projectId = await resolveProjectId(args);
+    resolution = await fetchResolution(args, projectId);
+  } catch (e) {
+    console.error(`piwi select: ${e.message}`);
+    return EXIT_ERROR3;
+  }
+  printWarnings(resolution);
+  if (resolution.estimate.count === 0) {
+    console.error(`piwi select: "${args.key}" resolved to 0 tests`);
+    return EXIT_ERROR3;
+  }
+  if (args.json) console.log(JSON.stringify(resolution, null, 2));
+  else console.log(resolution.materialization.args.join(" "));
+  return EXIT_OK3;
+}
+function resolvePlaywrightCli() {
+  const require2 = (0, import_node_module.createRequire)(path9.join(process.cwd(), "noop.js"));
+  for (const id of ["playwright/cli", "@playwright/test/cli", "playwright/lib/cli/cli"]) {
+    try {
+      return require2.resolve(id);
+    } catch {
+    }
+  }
+  return null;
+}
+function spawnPlaywright(pkgRunner, playwrightArgs, env) {
+  const cli = resolvePlaywrightCli();
+  const child = cli ? (0, import_node_child_process3.spawn)(process.execPath, [cli, "test", ...playwrightArgs], { stdio: "inherit", env }) : (0, import_node_child_process3.spawn)(process.platform === "win32" ? `${pkgRunner}.cmd` : pkgRunner, ["playwright", "test", ...playwrightArgs], {
+    stdio: "inherit",
+    env
+  });
+  return new Promise((resolve5) => {
+    child.on("error", (err) => {
+      console.error(`piwi run: could not start Playwright \u2014 ${err.message}`);
+      resolve5(EXIT_ERROR3);
+    });
+    child.on("exit", (code) => resolve5(code ?? EXIT_ERROR3));
+  });
+}
+async function runRunImpact(args, env) {
+  let projectId;
+  try {
+    projectId = await resolveProjectId(args);
+  } catch (e) {
+    if (args.strict) {
+      console.error(`piwi run: ${e.message}`);
+      return EXIT_ERROR3;
+    }
+    console.error(`piwi run: ${e.message} \u2014 running the full suite`);
+    return spawnPlaywright(args.pkgRunner, args.extra, env);
+  }
+  let impact;
+  try {
+    impact = await loadImpact(args, projectId);
+  } catch (e) {
+    if (args.strict) {
+      console.error(`piwi run: ${e.message}`);
+      return EXIT_ERROR3;
+    }
+    console.error(`piwi run: ${e.message} \u2014 running the full suite`);
+    return spawnPlaywright(args.pkgRunner, args.extra, 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))`
+    );
+    return spawnPlaywright(args.pkgRunner, args.extra, env);
+  }
+  if (impact.estimate.count === 0) {
+    console.error(`piwi run: no tests impacted by ${impact.impact.changedFiles} changed file(s) \u2014 nothing to run`);
+    return EXIT_OK3;
+  }
+  const runEnv = {
+    ...env,
+    PIWI_SELECTION: IMPACT_KEY,
+    PIWI_SELECTION_VERSION: "0",
+    PIWI_SELECTION_HASH: impact.resolvedHash,
+    PIWI_SELECTION_COUNT: String(impact.estimate.count)
+  };
+  console.error(`piwi run: impact \u2192 ${impact.estimate.count} test(s)`);
+  return spawnPlaywright(args.pkgRunner, [...impact.materialization.args, ...args.extra], runEnv);
+}
+async function runRun(argv, env = process.env) {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    console.log(USAGE5);
+    return EXIT_OK3;
+  }
+  let args;
+  try {
+    args = parseSelectArgs(argv, env);
+  } catch (e) {
+    console.error(`piwi run: ${e.message}
+`);
+    console.error(USAGE5);
+    return EXIT_ERROR3;
+  }
+  if (args.format === "json") {
+    console.error("piwi run: --format json cannot be run; use args, grep or files");
+    return EXIT_ERROR3;
+  }
+  if (args.key === IMPACT_KEY) {
+    if (!args.base) {
+      console.error("piwi run: impact needs a base ref \u2014 pass --base <ref> (e.g. --base origin/main)");
+      return EXIT_ERROR3;
+    }
+    return runRunImpact(args, env);
+  }
+  let projectId;
+  try {
+    projectId = await resolveProjectId(args);
+  } catch (e) {
+    if (args.strict) {
+      console.error(`piwi run: ${e.message}`);
+      return EXIT_ERROR3;
+    }
+    console.error(`piwi run: ${e.message} \u2014 running the full suite`);
+    return spawnPlaywright(args.pkgRunner, args.extra, env);
+  }
+  let outcome;
+  try {
+    outcome = await resolveWithCache(args, projectId);
+  } catch (e) {
+    console.error(`piwi run: ${e.message}`);
+    return EXIT_ERROR3;
+  }
+  if (!outcome) {
+    console.error("piwi run: dashboard unreachable and no cached resolution \u2014 running the full suite");
+    return spawnPlaywright(args.pkgRunner, args.extra, env);
+  }
+  const { resolution } = outcome;
+  printWarnings(resolution);
+  if (resolution.estimate.count === 0) {
+    console.error(`piwi run: "${args.key}" resolved to 0 tests`);
+    return EXIT_ERROR3;
+  }
+  const runEnv = {
+    ...env,
+    PIWI_SELECTION: resolution.key ?? args.key,
+    PIWI_SELECTION_VERSION: String(resolution.version ?? 0),
+    PIWI_SELECTION_HASH: resolution.resolvedHash,
+    PIWI_SELECTION_COUNT: String(resolution.estimate.count)
+  };
+  console.error(
+    `piwi run: ${args.key} \u2192 ${resolution.estimate.count} tests${resolution.materialization.format !== args.format ? ` (materialized as ${resolution.materialization.format})` : ""}`
+  );
+  return spawnPlaywright(args.pkgRunner, [...resolution.materialization.args, ...args.extra], runEnv);
+}
+
+// src/cli/index.ts
+var USAGE6 = `
 piwi \u2014 companion commands for the Piwi Dashboard reporter
 
 Usage:
@@ -1197,6 +1613,8 @@ Commands:
   init      Wire a Playwright project up to a Piwi Dashboard
   skills    Install the Piwi agent skills into this project
   gate      Fail a CI job on the dashboard's analysis of a run
+  select    Print the Playwright args for a saved test selection
+  run       Run a saved test selection with playwright test
   ai        Manage committed natural-language AI-step artifacts
 
 Run \`npx @piwitests/reporter <command> --help\` for a command's options.
@@ -1212,17 +1630,21 @@ async function main() {
       return runSkills(rest, findTemplatesDir(__dirname));
     case "gate":
       return runGate(rest);
+    case "select":
+      return runSelect(rest);
+    case "run":
+      return runRun(rest);
     case "ai":
       return runAi(rest);
     case void 0:
     case "-h":
     case "--help":
-      console.log(USAGE5);
+      console.log(USAGE6);
       return 0;
     default:
       console.error(`piwi: unknown command "${command}"
 `);
-      console.error(USAGE5);
+      console.error(USAGE6);
       return 2;
   }
 }

package/dist/global-setup-module.js

@@ -81,6 +81,7 @@ var DEFAULTS = {
   streaming: true,
   streamingBatchSize: 5,
   streamingBatchDelay: 2e3,
+  failOnFlakyTests: false,
   username: null,
   password: null,
   apiKey: null,
@@ -100,6 +101,7 @@ var PIWI_ENV_KEYS = {
   streamingBatchSize: "PIWI_STREAMING_BATCH_SIZE",
   streamingBatchDelay: "PIWI_STREAMING_BATCH_DELAY",
   liveFileUploads: "PIWI_LIVE_FILE_UPLOADS",
+  failOnFlakyTests: "PIWI_FAIL_ON_FLAKY_TESTS",
   uploadTraces: "PIWI_UPLOAD_TRACES",
   uploadReport: "PIWI_UPLOAD_REPORT",
   captureLocators: "PIWI_CAPTURE_LOCATORS",
@@ -135,6 +137,7 @@ var ENV_FALLBACK_SPECS = [
   { option: "streamingBatchSize", env: PIWI_ENV_KEYS.streamingBatchSize, kind: "number" },
   { option: "streamingBatchDelay", env: PIWI_ENV_KEYS.streamingBatchDelay, 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" },
@@ -506,7 +509,7 @@ function createGlobalSetup(options, userSetup) {
             projectName: opts.projectName
           })
         );
-        logger.debug(`Global setup: initialising run #${response.runId}`);
+        logger.debug(`Global setup: initializing run #${response.runId}`);
       }
     } catch (error) {
       logger.warn(`Could not register global setup: ${errorMessage(error)}`);

package/dist/index.d.ts

@@ -88,6 +88,14 @@ interface PiwiDashboardOptions {
     streamingBatchSize?: number;
     /** Max delay (ms) before flushing pending events during streaming. Defaults to `2000`. */
     streamingBatchDelay?: number;
+    /**
+     * Fail the run when any test was flaky (passed only after a retry). Forwarded
+     * to Playwright's native `failOnFlakyTests` config option (Playwright 1.52+)
+     * when the reporter is installed via `wrapConfig`, so a flaky-only run exits
+     * non-zero without any server round-trip. Defaults to `false`. Can also be
+     * set with `PIWI_FAIL_ON_FLAKY_TESTS`.
+     */
+    failOnFlakyTests?: boolean;
     /** Username for dashboard login (use `apiKey` instead when possible) */
     username?: string | null;
     /** Password for dashboard login (used with `username`) */
@@ -239,6 +247,8 @@ declare class PiwiDashboardReporter {
     private plannedTests;
     /** Ids of tests that actually reported via `onTestEnd`, to find the ones that never ran. */
     private reportedTestIds;
+    /** Per-test attempt history, keyed by `test.id`; snapshotted onto every attempt's payload. */
+    private attemptsByTest;
     private instanceId;
     private runLabel;
     private shardInfo;
@@ -248,6 +258,8 @@ declare class PiwiDashboardReporter {
     private viaDesktopApp;
     private isFullRun;
     private filterDetails;
+    /** Configured `maxFailures` (0 = unlimited) — disambiguates an interrupted run's unrun reason. */
+    private maxFailures;
     private httpClient;
     private uploader;
     private fileHandler;
@@ -265,6 +277,12 @@ declare class PiwiDashboardReporter {
     onTestBegin(test: TestCase, result: TestResult): void;
     /** Track suite-level setup steps (beforeAll/afterAll) not tied to any test */
     private setupSteps;
+    /**
+     * Step categories streamed live while the run executes. `pw:assert` is
+     * excluded: it is the polling noise of `expect()`, not a step a human
+     * watches; the meaningful readout is the `pw:expect` wrapper around it.
+     */
+    private static readonly LIVE_STEP_CATEGORIES;
     /** Playwright reporter hook: called when a step (including hook/fixture) begins */
     onStepBegin(test: TestCase | undefined, _result: TestResult | undefined, step: any): void;
     /** Playwright reporter hook: called when a step (including hook/fixture) ends */
@@ -276,13 +294,44 @@ declare class PiwiDashboardReporter {
      * (no `onTestEnd`) — typically because `maxFailures` cut the run short. These
      * carry no result, so they're emitted with zero duration and no error. In
      * streaming mode they're queued as complete events so the pre-finish drain
-     * sends them alongside the rest.
+     * sends them alongside the rest. The `reason` (global timeout / max failures /
+     * interrupted) is resolved once from the overall run status by the caller.
      */
     private materializeUnrunTests;
     /** Playwright reporter hook: called when the full test run finishes */
     onEnd(result: FullResult): Promise<void>;
 }
 
+interface ResolveSelectionResult {
+    key: string;
+    version: number;
+    resolvedHash: string;
+    resolvedCount: number;
+    /** A `--grep` regex that selects the resolved tests, when the grep format was produced. */
+    grep?: string;
+    /** File (or `file:line`) tokens, when grep fell back to a file materialization. */
+    files?: string[];
+}
+interface ResolveSelectionOptions {
+    /** Selection key; defaults to the `PIWI_SELECTION` env var. */
+    key?: string;
+    serverUrl?: string;
+    apiKey?: string | null;
+    /** Project name or id; defaults to `PIWI_PROJECT_NAME`. */
+    project?: string;
+    budgetMs?: number | null;
+    /** Throw instead of falling back to the full suite when resolution fails. */
+    strict?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve the configured selection. Returns `undefined` when no selection is
+ * named or (in non-strict mode) when the dashboard cannot be reached, so the
+ * config runs the full suite. On success it also writes `PIWI_SELECTION_*` so
+ * the reporter stamps the run with the resolved selection.
+ */
+declare function resolveSelection(options?: ResolveSelectionOptions): Promise<ResolveSelectionResult | undefined>;
+
 /**
  * Parameters are first-class: a template like `row for {name}` is the cache key,
  * so one entry serves every value. Placeholders survive compilation as `{{name}}`
@@ -345,4 +394,4 @@ declare function extendPiwiAi<TestArgs extends FixtureArgs, WorkerArgs extends F
  * exported from this file, it isn't part of the supported API.
  */
 
-export { type AiMode, type AiOnMiss, type PiwiAi, type PiwiDashboardOptions, PiwiDashboardReporter, createGlobalSetup, PiwiDashboardReporter as default, extendPiwiAi, piwiAiFixtures, wrapConfig };
+export { type AiMode, type AiOnMiss, type PiwiAi, type PiwiDashboardOptions, PiwiDashboardReporter, type ResolveSelectionOptions, type ResolveSelectionResult, createGlobalSetup, PiwiDashboardReporter as default, extendPiwiAi, piwiAiFixtures, resolveSelection, wrapConfig };