@piwitests/reporter 0.25.0 → 0.26.1

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 };

package/dist/index.js

@@ -37,6 +37,7 @@ __export(index_exports, {
   extendPiwiFixtures: () => extendPiwiFixtures,
   piwiAiFixtures: () => piwiAiFixtures,
   piwiFixtures: () => piwiFixtures,
+  resolveSelection: () => resolveSelection,
   wrapConfig: () => wrapConfig
 });
 module.exports = __toCommonJS(index_exports);
@@ -79,6 +80,7 @@ var DEFAULTS = {
   streaming: true,
   streamingBatchSize: 5,
   streamingBatchDelay: 2e3,
+  failOnFlakyTests: false,
   username: null,
   password: null,
   apiKey: null,
@@ -98,6 +100,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",
@@ -116,6 +119,12 @@ var PIWI_ENV_KEYS = {
   aiScreenshotFallback: "PIWI_AI_SCREENSHOT_FALLBACK"
 };
 var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
+var PIWI_SELECTION_ENV = {
+  key: "PIWI_SELECTION",
+  version: "PIWI_SELECTION_VERSION",
+  hash: "PIWI_SELECTION_HASH",
+  count: "PIWI_SELECTION_COUNT"
+};
 function readBool(val) {
   if (val === void 0) return void 0;
   return val === "true";
@@ -133,6 +142,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" },
@@ -430,8 +440,8 @@ function resolveOverallStatus(result, counters) {
   const STATUS_MAP = {
     passed: "passed",
     failed: "failed",
-    timedout: "failed",
-    interrupted: "failed"
+    timedout: "timedout",
+    interrupted: "interrupted"
   };
   if (result?.status) return STATUS_MAP[result.status] ?? "failed";
   if (counters.failedTests === 0 && counters.timedOutTests === 0 && counters.totalTests > 0) return "passed";
@@ -448,6 +458,7 @@ function toWireTestCase(tc) {
     timeout: rest.timeout ?? null,
     error: rest.error,
     retries: rest.retries,
+    attempts: rest.attempts || null,
     workerIndex: rest.workerIndex ?? null,
     shardIndex: rest.shardIndex ?? null,
     startedAt: rest.startedAt ?? null,
@@ -470,7 +481,9 @@ function toWireTestCase(tc) {
     testAnnotations: rest.testAnnotations ?? null,
     tags: rest.tags ?? null,
     testMeta: rest.testMeta ?? null,
-    locatorSnapshots: rest.locatorSnapshots || null
+    locatorSnapshots: rest.locatorSnapshots || null,
+    didNotRunReason: rest.didNotRunReason ?? null,
+    blockedBy: rest.blockedBy ?? null
   };
 }
 function serializeRun(payload, opts) {
@@ -523,8 +536,8 @@ var Uploader = class {
       auth
     );
     this.logger.info(`Successfully uploaded test results`);
-    if (response.testRunId) {
-      this.logger.info(`Test Run ID: ${response.testRunId}, Project ID: ${response.projectId}`);
+    if (response.runId) {
+      this.logger.info(`Test Run ID: ${response.runId}, Project ID: ${response.projectId}`);
     }
     return response;
   }
@@ -538,8 +551,8 @@ var Uploader = class {
     await this.appendFilesToForm(form, payload.testCases, reportOptions.uploadTraces);
     const response = await this.httpClient.postFormData("/api/test-runs/upload", form, auth);
     this.logger.info(`Successfully uploaded test results with files`);
-    if (response.testRunId) {
-      this.logger.info(`Test Run ID: ${response.testRunId}, Project ID: ${response.projectId}`);
+    if (response.runId) {
+      this.logger.info(`Test Run ID: ${response.runId}, Project ID: ${response.projectId}`);
     }
     if (response.reports) {
       for (const r of response.reports) this.logger.info(`${r.label}: ${r.path}`);
@@ -549,7 +562,7 @@ var Uploader = class {
   /** Upload report files for an already-submitted streaming run */
   async uploadReportsForStreamingRun(projectName, runId, reportOptions, startTime, auth) {
     const form = new import_form_data2.default();
-    form.append("testRunId", String(runId));
+    form.append("runId", String(runId));
     form.append("projectName", projectName);
     form.append(
       "testRun",
@@ -1012,6 +1025,39 @@ var FileHandler = class {
 
 // src/internal/collect/metadata-collector.ts
 var import_node_child_process = require("child_process");
+var DETACHED_HEAD = "HEAD";
+function resolveScmBranch(env, gitBranch) {
+  const pick = (...names) => {
+    for (const name of names) {
+      const value = env[name]?.trim();
+      if (value) return value;
+    }
+    return void 0;
+  };
+  const override = env.PIWI_BRANCH?.trim();
+  if (override) return override;
+  let provider;
+  if (env.JENKINS_URL) provider = pick("CHANGE_BRANCH", "BRANCH_NAME");
+  else if (env.GITHUB_ACTIONS) provider = pick("GITHUB_HEAD_REF", "GITHUB_REF_NAME");
+  else if (env.GITLAB_CI) provider = pick("CI_MERGE_REQUEST_SOURCE_BRANCH_NAME", "CI_COMMIT_REF_NAME");
+  else if (env.CIRCLECI) provider = pick("CIRCLE_BRANCH");
+  else if (env.TRAVIS) provider = pick("TRAVIS_PULL_REQUEST_BRANCH", "TRAVIS_BRANCH");
+  else if (env.TF_BUILD) provider = pick("SYSTEM_PULLREQUEST_SOURCEBRANCH", "BUILD_SOURCEBRANCHNAME");
+  else if (env.BITBUCKET_BUILD_NUMBER) provider = pick("BITBUCKET_BRANCH");
+  if (provider) return normalizeRef(provider);
+  const trimmed = gitBranch?.trim();
+  if (trimmed && trimmed !== DETACHED_HEAD) return trimmed;
+  return void 0;
+}
+function resolveScmPrNumber(env) {
+  const githubRef = env.GITHUB_ACTIONS ? env.GITHUB_REF?.match(/^refs\/pull\/(\d+)\/(?:merge|head)$/) : void 0;
+  const raw = githubRef?.[1] ?? env.CI_MERGE_REQUEST_IID ?? env.BITBUCKET_PR_ID ?? env.SYSTEM_PULLREQUEST_PULLREQUESTNUMBER ?? env.CHANGE_ID;
+  const trimmed = raw?.trim();
+  return trimmed && /^\d+$/.test(trimmed) ? trimmed : void 0;
+}
+function normalizeRef(ref) {
+  return ref.replace(/^refs\/heads\//, "");
+}
 var MetadataCollector = class {
   constructor(logger = new Logger()) {
     this.logger = logger;
@@ -1117,6 +1163,7 @@ var MetadataCollector = class {
   }
   collectScmInfo(_options) {
     const scm = {};
+    let gitBranch;
     try {
       const execOpts = {
         encoding: "utf8",
@@ -1125,7 +1172,7 @@ var MetadataCollector = class {
         stdio: ["ignore", "pipe", "ignore"]
       };
       scm.commit = (0, import_node_child_process.execSync)("git rev-parse HEAD", execOpts).trim();
-      scm.branch = (0, import_node_child_process.execSync)("git rev-parse --abbrev-ref HEAD", execOpts).trim();
+      gitBranch = (0, import_node_child_process.execSync)("git rev-parse --abbrev-ref HEAD", execOpts).trim();
       scm.author = (0, import_node_child_process.execSync)('git log -1 --pretty=format:"%an"', execOpts).trim();
       scm.commitMessage = (0, import_node_child_process.execSync)('git log -1 --pretty=format:"%s"', execOpts).trim();
       try {
@@ -1135,6 +1182,10 @@ var MetadataCollector = class {
     } catch (error) {
       this.logger.debug(`Git info not available: ${errorMessage(error)}`);
     }
+    const branch = resolveScmBranch(process.env, gitBranch);
+    if (branch) scm.branch = branch;
+    const prNumber = resolveScmPrNumber(process.env);
+    if (prNumber) scm.prNumber = prNumber;
     return Object.keys(scm).length > 0 ? scm : void 0;
   }
   collectCiInfo() {
@@ -1421,8 +1472,8 @@ var StreamManager = class {
         if (this.pendingBeginEvents.length > 0) {
           this.pendingEvents = [...this.pendingBeginEvents, ...this.pendingEvents];
           this.pendingBeginEvents = [];
-          this.flush();
         }
+        if (this.pendingEvents.length > 0) this.flush();
       }
     } catch (error) {
       if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
@@ -1934,6 +1985,17 @@ function detectCliFileFilters(argv = process.argv) {
   return files;
 }
 
+// src/internal/support/selection-env.ts
+function readSelectionStamp(env = process.env) {
+  const key = env[PIWI_SELECTION_ENV.key];
+  if (!key) return null;
+  const version = Number(env[PIWI_SELECTION_ENV.version]);
+  const resolvedCount = Number(env[PIWI_SELECTION_ENV.count]);
+  const resolvedHash = env[PIWI_SELECTION_ENV.hash] ?? "";
+  if (!Number.isFinite(version) || !Number.isFinite(resolvedCount) || !resolvedHash) return null;
+  return { key, version, resolvedHash, resolvedCount };
+}
+
 // src/public/global-setup.ts
 var path10 = __toESM(require("path"));
 var fs11 = __toESM(require("fs"));
@@ -2024,7 +2086,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)}`);
@@ -2067,8 +2129,12 @@ function wrapConfig(config, piwiOptions) {
     globalSetupModules.push(...orig);
   }
   globalSetupModules.push(resolveSetupModule());
+  const forwarded = {};
+  const failOnFlaky = piwiOptions?.failOnFlakyTests ?? readBool(process.env[PIWI_ENV_KEYS.failOnFlakyTests]);
+  if (failOnFlaky === true) forwarded.failOnFlakyTests = true;
   return {
     ...config,
+    ...forwarded,
     reporter: injectReporter(config.reporter, piwiOptions),
     globalSetup: globalSetupModules.length === 1 ? globalSetupModules[0] : globalSetupModules
   };
@@ -2093,6 +2159,45 @@ function classifyStatus(rawStatus, annotations) {
   const intentional = annotations.some((a) => a.type === "skip" || a.type === "fixme");
   return intentional ? "skipped" : "didnotrun";
 }
+function resolveUnrunReason(runStatus, opts) {
+  if (runStatus === "timedout") return "global-timeout";
+  if (opts.maxFailures > 0 && opts.failures >= opts.maxFailures) return "max-failures";
+  return "interrupted";
+}
+function fileOf(location) {
+  return location.replace(/:\d+:\d+$/, "");
+}
+function suiteKey(suitePath) {
+  return (suitePath ?? []).join("");
+}
+function sharedPrefixDepth(a, b) {
+  let depth = 0;
+  while (depth < a.length && depth < b.length && a[depth] === b[depth]) depth++;
+  return depth;
+}
+function linkBlockedTests(cases) {
+  const blockers = cases.filter((c) => c.status === "failed" || c.status === "timedOut" || c.status === "timedout");
+  if (blockers.length === 0) return;
+  for (const c of cases) {
+    if (c.didNotRunReason !== "previous-failure") continue;
+    const file = fileOf(c.location);
+    const inFile = blockers.filter((b) => fileOf(b.location) === file);
+    if (inFile.length === 0) continue;
+    const key = suiteKey(c.suitePath);
+    let blocker = inFile.find((b) => suiteKey(b.suitePath) === key);
+    if (!blocker) {
+      let bestDepth = 0;
+      for (const b of inFile) {
+        const depth = sharedPrefixDepth(c.suitePath ?? [], b.suitePath ?? []);
+        if (depth > bestDepth) {
+          bestDepth = depth;
+          blocker = b;
+        }
+      }
+    }
+    if (blocker) c.blockedBy = blocker.location;
+  }
+}
 
 // ../core/src/test-meta.ts
 var PIWI_ANNOTATION_PREFIX = "piwi:";
@@ -2462,7 +2567,7 @@ var RunSubmitter = class {
         auth
       );
       this.recovery.clear();
-      return { done: true, output: this.buildOutput(response?.testRunId, response?.projectId, run, overallStatus) };
+      return { done: true, output: this.buildOutput(response?.runId, response?.projectId, run, overallStatus) };
     } catch (error) {
       if (error instanceof HttpError && error.status === 401 && !auth) {
         this.logAuthRequired(run.options.serverUrl);
@@ -2478,7 +2583,7 @@ var RunSubmitter = class {
     try {
       const response = await this.uploader.uploadJSON(payload, auth);
       this.recovery.clear();
-      return { done: true, output: this.buildOutput(response?.testRunId, response?.projectId, run, overallStatus) };
+      return { done: true, output: this.buildOutput(response?.runId, response?.projectId, run, overallStatus) };
     } catch (error) {
       if (error instanceof HttpError && error.status === 401 && !auth) {
         this.logAuthRequired(run.options.serverUrl);
@@ -2505,7 +2610,7 @@ function testLocation(test) {
   const relativeFilePath = path14.relative(process.cwd(), test.location.file).split(path14.sep).join("/");
   return `${relativeFilePath}:${test.location.line}:${test.location.column}`;
 }
-var PiwiDashboardReporter = class {
+var PiwiDashboardReporter = class _PiwiDashboardReporter {
   constructor(rawOptions = {}) {
     this.testCases = [];
     this.startTime = null;
@@ -2521,11 +2626,15 @@ var PiwiDashboardReporter = class {
     this.plannedTests = [];
     /** Ids of tests that actually reported via `onTestEnd`, to find the ones that never ran. */
     this.reportedTestIds = /* @__PURE__ */ new Set();
+    /** Per-test attempt history, keyed by `test.id`; snapshotted onto every attempt's payload. */
+    this.attemptsByTest = /* @__PURE__ */ new Map();
     this.runLabel = null;
     this.shardInfo = null;
     this.metadata = {};
     this.isFullRun = true;
     this.filterDetails = null;
+    /** Configured `maxFailures` (0 = unlimited) — disambiguates an interrupted run's unrun reason. */
+    this.maxFailures = 0;
     this.streamManager = null;
     /** Track suite-level setup steps (beforeAll/afterAll) not tied to any test */
     this.setupSteps = [];
@@ -2573,6 +2682,7 @@ var PiwiDashboardReporter = class {
     }
     this.startTime = (/* @__PURE__ */ new Date()).toISOString();
     this.playwrightVersion = config.version;
+    this.maxFailures = config.maxFailures ?? 0;
     this.logger.info(
       `Starting test run for project: ${this.options.projectName} (Playwright v${this.playwrightVersion})`
     );
@@ -2582,14 +2692,18 @@ var PiwiDashboardReporter = class {
     const grep = grepRe && grepRe.source !== ".*" ? grepRe.source : void 0;
     const grepInvert = grepInvertRe?.source;
     const fileFilters = detectCliFileFilters();
-    if (grep || grepInvert || fileFilters.length > 0) {
+    const selection = readSelectionStamp();
+    if (grep || grepInvert || fileFilters.length > 0 || selection) {
       this.isFullRun = false;
       this.filterDetails = {
         ...grep ? { grep } : {},
         ...grepInvert ? { grepInvert } : {},
-        ...fileFilters.length > 0 ? { files: fileFilters } : {}
+        ...fileFilters.length > 0 ? { files: fileFilters } : {},
+        ...selection ? { selection } : {}
       };
-      this.logger.info("Partial run detected (filter active)");
+      this.logger.info(
+        selection ? `Selection run detected (${selection.key})` : "Partial run detected (filter active)"
+      );
     }
     this.metadata = this.metadataCollector.collect(config, suite, this.options);
     this.plannedTests = suite.allTests();
@@ -2626,11 +2740,19 @@ var PiwiDashboardReporter = class {
       this.streamManager.queueBeginEvent(toWireTestCase(beginEvent));
     }
   }
+  static {
+    /**
+     * 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.
+     */
+    this.LIVE_STEP_CATEGORIES = /* @__PURE__ */ new Set(["hook", "fixture", "pw:api", "pw:expect"]);
+  }
   /** Playwright reporter hook: called when a step (including hook/fixture) begins */
   onStepBegin(test, _result, step) {
-    if (!this.enabled || !this.streamManager?.enabled) return;
+    if (!this.enabled || !this.streamManager) return;
     const cat = step.category;
-    if (cat !== "hook" && cat !== "fixture") return;
+    if (!_PiwiDashboardReporter.LIVE_STEP_CATEGORIES.has(cat)) return;
     const event = {
       type: "step-begin",
       title: step.title,
@@ -2644,10 +2766,9 @@ var PiwiDashboardReporter = class {
   }
   /** Playwright reporter hook: called when a step (including hook/fixture) ends */
   onStepEnd(test, _result, step) {
+    if (!this.enabled || !this.streamManager) return;
     const cat = step.category;
-    if (cat === "pw:api") return;
-    if (!this.enabled || !this.streamManager?.enabled) return;
-    if (cat !== "hook" && cat !== "fixture") return;
+    if (!_PiwiDashboardReporter.LIVE_STEP_CATEGORIES.has(cat)) return;
     const workerIndex = workerIndexOf(_result);
     const startedAt = step.startTime instanceof Date ? step.startTime.getTime() : null;
     const event = {
@@ -2662,7 +2783,7 @@ var PiwiDashboardReporter = class {
       startedAt
     };
     this.streamManager?.queueEvent(event);
-    if (!test && startedAt) {
+    if (!test && startedAt && (cat === "hook" || cat === "fixture")) {
       this.setupSteps.push({
         title: step.title,
         category: cat,
@@ -2682,6 +2803,14 @@ var PiwiDashboardReporter = class {
     const annotations = mergeAnnotations(test, result);
     const status = classifyStatus(result.status, annotations);
     const tags = collectTestTags(test);
+    const attempts = this.attemptsByTest.get(test.id) ?? [];
+    attempts.push({
+      retry: result.retry,
+      status,
+      duration: result.duration,
+      startedAt: result.startTime ? result.startTime.getTime() : null
+    });
+    this.attemptsByTest.set(test.id, attempts);
     const testCase = {
       type: "complete",
       title: test.title,
@@ -2693,6 +2822,7 @@ var PiwiDashboardReporter = class {
       timeout: test.timeout ?? null,
       error: buildErrorText(result),
       retries: result.retry,
+      attempts: attempts.map((a) => ({ ...a })),
       workerIndex: workerIndexOf(result),
       shardIndex: this.shardInfo?.current ?? null,
       startedAt: result.startTime ? result.startTime.getTime() : null,
@@ -2702,7 +2832,10 @@ var PiwiDashboardReporter = class {
       suiteConfig,
       testAnnotations: annotations.length ? annotations : null,
       tags: tags.length ? tags : null,
-      testMeta: collectTestMetadata(annotations)
+      testMeta: collectTestMetadata(annotations),
+      // An annotation-less skip reclassified to `didnotrun` is a serial-group
+      // cascade: an earlier test failed and Playwright skipped the rest.
+      didNotRunReason: status === "didnotrun" ? "previous-failure" : null
     };
     if (result.status === "failed" || result.status === "timedOut") {
       const failingLine = extractFailingLine(testCase.error, test.location.file, test.location.line);
@@ -2746,6 +2879,7 @@ var PiwiDashboardReporter = class {
         break;
     }
     this.testCases.push(testCase);
+    if (status === "didnotrun") linkBlockedTests(this.testCases);
     if (this.streamManager) {
       this.streamManager.queueEvent(toWireTestCase(testCase));
       if (this.options.liveFileUploads) this.streamManager.scheduleLiveUpload(testCase);
@@ -2756,9 +2890,10 @@ var PiwiDashboardReporter = class {
    * (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.
    */
-  materializeUnrunTests() {
+  materializeUnrunTests(reason) {
     for (const test of this.plannedTests) {
       if (this.reportedTestIds.has(test.id)) continue;
       const { suitePath, suiteConfig } = this.metadataCollector.getSuiteInfo(test);
@@ -2782,7 +2917,8 @@ var PiwiDashboardReporter = class {
         suiteConfig,
         testAnnotations: declaredAnnotations.length ? declaredAnnotations : null,
         tags: tags.length ? tags : null,
-        testMeta: collectTestMetadata(declaredAnnotations)
+        testMeta: collectTestMetadata(declaredAnnotations),
+        didNotRunReason: reason
       };
       this.testCases.push(testCase);
       this.totalTests++;
@@ -2795,7 +2931,11 @@ var PiwiDashboardReporter = class {
   /** Playwright reporter hook: called when the full test run finishes */
   async onEnd(result) {
     if (!this.enabled) return;
-    this.materializeUnrunTests();
+    const unrunReason = resolveUnrunReason(result?.status, {
+      maxFailures: this.maxFailures,
+      failures: this.failedTests + this.timedOutTests
+    });
+    this.materializeUnrunTests(unrunReason);
     await this.submitter.submit(
       {
         options: this.options,
@@ -2821,6 +2961,79 @@ var PiwiDashboardReporter = class {
   }
 };
 
+// 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();
+}
+
+// src/public/selection.ts
+async function resolveSelection(options = {}) {
+  const env = options.env ?? process.env;
+  const key = options.key ?? env[PIWI_SELECTION_ENV.key];
+  if (!key) return void 0;
+  const serverUrl = (options.serverUrl ?? env[PIWI_ENV_KEYS.serverUrl] ?? "").replace(/\/$/, "");
+  const apiKey = options.apiKey ?? env[PIWI_ENV_KEYS.apiKey] ?? null;
+  const project = options.project ?? env[PIWI_ENV_KEYS.projectName] ?? "";
+  if (!serverUrl) {
+    if (options.strict) throw new Error("resolveSelection: no dashboard URL (set PIWI_DASHBOARD_URL)");
+    return void 0;
+  }
+  const clientOptions = { serverUrl, apiKey, project, key, format: "grep", budgetMs: options.budgetMs ?? null };
+  try {
+    const projectId = await resolveProjectId(clientOptions);
+    const resolution = await fetchResolution(clientOptions, projectId);
+    if (resolution.estimate.count === 0) {
+      if (options.strict) throw new Error(`resolveSelection: "${key}" resolved to 0 tests`);
+      console.warn(`[Piwi Dashboard] selection "${key}" resolved to 0 tests \u2014 running the full suite`);
+      return void 0;
+    }
+    env[PIWI_SELECTION_ENV.key] = resolution.key ?? key;
+    env[PIWI_SELECTION_ENV.version] = String(resolution.version ?? 0);
+    env[PIWI_SELECTION_ENV.hash] = resolution.resolvedHash;
+    env[PIWI_SELECTION_ENV.count] = String(resolution.estimate.count);
+    const args = resolution.materialization.args;
+    const result = {
+      key: resolution.key ?? key,
+      version: resolution.version ?? 0,
+      resolvedHash: resolution.resolvedHash,
+      resolvedCount: resolution.estimate.count
+    };
+    if (args[0] === "--grep") result.grep = args[1];
+    else result.files = args;
+    return result;
+  } catch (e) {
+    if (options.strict) throw e;
+    console.warn(
+      `[Piwi Dashboard] selection "${key}" could not be resolved \u2014 running the full suite (${e.message})`
+    );
+    return void 0;
+  }
+}
+
 // src/internal/capture/capture-fixtures.ts
 var import_node_zlib = require("zlib");
 
@@ -6362,5 +6575,6 @@ var index_default = PiwiDashboardReporter;
   extendPiwiFixtures,
   piwiAiFixtures,
   piwiFixtures,
+  resolveSelection,
   wrapConfig
 });

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Playwright reporter that streams results, traces and HTML reports to a Piwi Dashboard instance",
   "url": "https://github.com/PiwiTests/platform",
-  "homepage": "https://piwitests.github.io",
+  "homepage": "https://piwitests.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/PiwiTests/platform"

package/templates/skills/investigate-failure/SKILL.md

@@ -5,7 +5,7 @@ description: Investigate a failed test run recorded in Piwi Dashboard and propos
 
 # Investigate a Piwi failure
 
-Turn a failed run in [Piwi Dashboard](https://piwitests.github.io) into a grounded diagnosis and a concrete fix. Piwi has already gathered the evidence — the error text, the steps that ran, console output, failing network calls, a suggested locator, and the source diff since the last passing run. Use that instead of guessing.
+Turn a failed run in [Piwi Dashboard](https://piwitests.dev) into a grounded diagnosis and a concrete fix. Piwi has already gathered the evidence — the error text, the steps that ran, console output, failing network calls, a suggested locator, and the source diff since the last passing run. Use that instead of guessing.
 
 ## How you reach Piwi
 

package/templates/skills/run-the-right-tests/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: run-the-right-tests
+description: Pick and run the right subset of Playwright tests using Piwi's data-driven selections, instead of always running the whole suite. Use when the user asks to "run smoke tests", "run the right tests", "just run what's relevant", "verify this fix", or wants a fast, targeted test loop rather than the full run.
+---
+
+# Run the right tests with Piwi selections
+
+Running the whole suite for every change is slow, and hand-maintained grep patterns go stale. A Piwi **selection** is a named, declarative subset of the suite that Piwi resolves from run history — smoke, critical-and-stable, recently-broken, the best five minutes. This skill picks the selection that fits the task and runs exactly those tests.
+
+## How you reach Piwi
+
+Prefer the **Piwi MCP server** if it is connected (`list_selections`, `resolve_selection`, `preview_selection`). Otherwise use the reporter CLI (`npx @piwitests/reporter select|run`) with `PIWI_DASHBOARD_URL` / `PIWI_API_KEY` / `PIWI_PROJECT_NAME` set, or the dashboard's **Selections** tab.
+
+## Steps
+
+1. **See what selections exist.** Call `list_selections` for the project. Every project has the built-ins `failed` (tests whose latest run failed) and `quarantine-free`, plus any the team saved (often `smoke`). Pick the one that matches the intent:
+   - About to make a broad change, or want a quick confidence check → `smoke` (or `preview_selection` with `{ "include": [{ "tags": ["smoke"] }] }`).
+   - Iterating on a fix → `failed`, or a `{ "include": [{ "failedInLastRuns": 5 }] }` preview.
+   - Time-boxed → resolve any selection with a `budgetMs` (e.g. 300000 for five minutes).
+
+2. **Resolve it to a command.** Call `resolve_selection` with the key (and optional `budgetMs`). You get back the matching tests, an estimate, and a ready-to-run `playwright test` command. Check the count and warnings first — a selection that matches **zero** tests is a red flag (too narrow, or nothing qualifies), and a `quarantined-included` warning means a flaky test is in the set.
+
+3. **Run it.** The most reliable way is the reporter CLI, which resolves and runs in one step and stamps the run so the dashboard names the subset:
+   ```
+   npx @piwitests/reporter run <key>
+   ```
+   Or run the materialized command `resolve_selection` returned directly with `playwright test`. Pass extra Playwright args after `--` (e.g. `-- --workers=4`).
+
+4. **After a fix, verify with the same selection.** Re-run the selection that covered the failure and confirm it now passes. In CI, `npx @piwitests/reporter gate --require-selection <key>` fails the build if any test the selection currently matches did not run or did not pass — catching a smoke job that silently shrank.
+
+5. **Report.** State which selection you ran, how many tests it resolved to, and the outcome. If no saved selection fit, suggest one (a `preview_selection` definition the team could save) rather than falling back to the whole suite silently.
+
+## Guardrails
+
+- A selection that resolves to **zero** tests is never "nothing to do" — it means the definition is wrong. Stop and say so.
+- Selections choose what to *run*; they never hide a failure. Quarantine is the tool for a test whose verdict should not block a merge — do not use a selection to route around a red test.
+- Don't invent a selection key. Use `list_selections` to see the real ones, and `preview_selection` for an ad-hoc subset.
+- The full suite stays the baseline. Selections are for the fast loops between full runs, not a permanent replacement.

package/templates/skills/setup-piwi/SKILL.md

@@ -5,7 +5,7 @@ description: Wire a Playwright project up to a Piwi Dashboard — install the re
 
 # Set up Piwi in a Playwright project
 
-Connect a Playwright test suite to a [Piwi Dashboard](https://piwitests.github.io) so every run is uploaded, kept, and analyzed. The mechanical work is done by a deterministic command; your job is to gather the right inputs, run it, finish anything it flags, and prove a run reaches the dashboard.
+Connect a Playwright test suite to a [Piwi Dashboard](https://piwitests.dev) so every run is uploaded, kept, and analyzed. The mechanical work is done by a deterministic command; your job is to gather the right inputs, run it, finish anything it flags, and prove a run reaches the dashboard.
 
 ## Before you start