squally-reporter 0.3.0 → 0.5.0

package/dist/index.js

@@ -3,11 +3,179 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.__internal = void 0;
 const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
 const node_path_1 = __importDefault(require("node:path"));
 const undici_1 = require("undici");
+// Mirrors squally-app's ingest contract (lib/ingest-contract.ts,
+// FIELD_LIMITS). Kept as a copy on purpose - the reporter ships independently
+// of the app and cannot import from it - which means this table has to be
+// updated when that one changes. It is deliberately not "roughly right": the
+// server rejects the ENTIRE payload on the FIRST field that is too long
+// (v1) or the ENTIRE BATCH (v2), so one over-long value used to cost a whole
+// run, and under v2 still costs a whole batch, with a bare "400 Bad Request"
+// as the only clue if this table drifts.
+//
+// ciProvider is absent because the server does not length-check it, and this
+// reporter only ever sends one of four fixed strings for it.
+const FIELD_LIMITS = {
+    branch: 250,
+    commitSha: 100,
+    commitMessage: 500,
+    authorName: 100,
+    testedRevision: 200,
+    eventType: 100,
+    testName: 500,
+    filePath: 500,
+    errorMessage: 5000,
+    errorStack: 20000,
+};
+// v2-only limits (squally-app/lib/ingest-v2-contract.ts, V2_FIELD_LIMITS).
+// Mirrored the same way as FIELD_LIMITS above, for the same reason.
+const V2_FIELD_LIMITS = {
+    ciRunId: 200,
+    projectName: 200,
+    browserName: 50,
+    errorContext: 20000,
+    tag: 100,
+    playwrightVersion: 50,
+    os: 100,
+    osVersion: 50,
+};
+const MAX_TAGS = 20;
+const MAX_ERRORS_PER_RESULT = 10;
+const MAX_ERROR_SNIPPET = 2000;
+// ASCII only, like everything else in this file, and short: it has to fit
+// INSIDE the limit it is protecting, and authorName only has 100 characters
+// to give away.
+const TRUNCATION_MARKER = "... [truncated]";
+// Squally rejects a payload with more than this many entries outright - the
+// whole run, not the surplus. Mirrored here so the reporter can say so up
+// front instead of the customer finding out from a 400 after the suite has
+// already finished.
+//
+// Deliberately NOT enforced by trimming: unlike an over-long error message,
+// the surplus here is test results, and dropping them would turn a loud
+// failure into a run that quietly looks like those tests never existed. The
+// reporter reports what happened or says why it could not - it does not
+// invent a smaller truth.
+//
+// Retries count as separate entries, so a suite of 2 000 tests reaches this
+// faster than the number suggests. Under v2 this is a soft ceiling in a
+// different sense than under v1: it no longer discards the WHOLE run (results
+// stream progressively, and the app itself has no total-per-run cap in v2 -
+// see docs/ingest-v2-spec.md section 0, "the payload is bounded twice over"
+// describes v1's problem specifically). Kept here anyway as an early,
+// friendly warning for a suite that large, since it usually indicates a
+// configuration problem (e.g. retries left cranked up) worth knowing about
+// regardless of whether v2 would technically accept it in smaller pieces.
+const MAX_TEST_RESULTS_WARNING = 5000;
+// Squally accepts at most this many results per APPEND request (spec section
+// 1.3). A batch larger than this is split into sequential requests rather
+// than rejected - see flush() below.
+const BATCH_MAX_RESULTS = 500;
+// Visible rather than silent: a value that was cut says so, so nobody debugs
+// a "wrong" commit message that is merely shortened. For testName/filePath
+// this also alters Squally's test identity - unavoidable, since the
+// alternative is losing the run outright, and two names sharing their first
+// 500 characters would collide either way.
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    if (max <= TRUNCATION_MARKER.length)
+        return value.slice(0, max);
+    return value.slice(0, max - TRUNCATION_MARKER.length) + TRUNCATION_MARKER;
+}
+function truncateOrNull(value, max) {
+    return value === null ? null : truncate(value, max);
+}
+// How much of a server error body to put in the log. Enough for the server's
+// own one-line explanation, bounded so that an unexpected HTML error page
+// from a proxy cannot dump kilobytes into the customer's CI output.
+const ERROR_BODY_LOG_LIMIT = 500;
+// Sent on every request to squally-app (not on the artifact PUT to R2's
+// presigned URL - that goes straight to Cloudflare storage, not through the
+// app, and R2 has no use for it). Server-side, a customer's reporter version
+// was previously not determinable at all - every request looked identical
+// regardless of which release sent it, which made both support ("what
+// version is this customer on") and a future deprecation notice
+// impossible to target.
+//
+// Read from this package's own package.json rather than hardcoded, so it can
+// never drift from the version actually being published - package.json is
+// always included in a published npm tarball regardless of the "files"
+// field, and dist/index.js's parent directory is the package root.
+const REPORTER_VERSION = require("../package.json").version;
+const USER_AGENT = `squally-reporter/${REPORTER_VERSION}`;
+// undici leaves headersTimeout and bodyTimeout at 300 000 ms each when they
+// are not set. A hung server would otherwise cost 5 minutes per request -
+// with v2's streaming appends that could mean many such waits spread across
+// one run, not just a handful at the very end as in v1.
+//
+// Two budgets, because the two kinds of request are not comparable. The JSON
+// calls (begin/append/complete/rules) exchange kilobytes and have no business
+// taking longer than half a minute. An upload can be a 50 MB trace over a CI
+// runner's modest uplink, where two minutes is tight-ish but still far short
+// of "hung".
+const API_REQUEST_TIMEOUT_MS = 30000;
+const UPLOAD_REQUEST_TIMEOUT_MS = 120000;
+// Shorter than API_REQUEST_TIMEOUT_MS on purpose (spec section 6): the rules
+// call is best-effort and its result is not yet used for anything, so it has
+// no business holding anything up as long as the other calls do.
+const RULES_REQUEST_TIMEOUT_MS = 5000;
+// --- Batching (spec section 3.2) --------------------------------------------
+//
+// Flush on whichever comes first: 25 results, or 2 seconds. 25 is a LATENCY
+// limit, not a size limit (BATCH_MAX_RESULTS above is the size limit) - it
+// keeps a normal suite's "running" view within a few seconds of the suite,
+// while a very large run needs many requests spread over its whole duration
+// rather than one enormous one. 2 seconds is the shortest window that
+// cannot, on its own, exceed the ingest firewall rule (60 requests/60 s per
+// API key): 60 s / 2 s = 30 requests/minute, half of 60.
+const FLUSH_THRESHOLD_RESULTS = 25;
+const FLUSH_INTERVAL_MS = 2000;
+// --- Retry policy (spec section 3.2) ----------------------------------------
+//
+// Two independent policies, both applied by requestJson() below via separate
+// counters (not one shared counter) - a run of alternating 429s and 5xxs
+// should not let an early 429 retry eat into the budget a LATER, unrelated
+// 5xx is entitled to, or vice versa.
+const RATE_LIMIT_MAX_ATTEMPTS = 5;
+const RATE_LIMIT_BACKOFF_BASE_MS = 1000;
+const RATE_LIMIT_BACKOFF_CAP_MS = 30000;
+const SERVER_ERROR_MAX_ATTEMPTS = 2; // i.e. one retry
+const SERVER_ERROR_RETRY_DELAY_MS = 1000;
+const NETWORK_ERROR_MAX_ATTEMPTS = 2; // treated the same as a 5xx - one retry
+// (decision, spec section 3.2 closes 8.7) Drain budget at onEnd: 5 seconds,
+// ON TOP OF EXIT_DRAIN_MS below. At the flush cadence above, at most one or
+// two batches are ever in flight when onEnd fires; 5 s comfortably covers a
+// single retry cycle. Also covers waiting for onBegin itself to resolve, if
+// it is still pending - see drainAndComplete().
+const DRAIN_BUDGET_MS = 5000;
+function describeRequestError(err, timeoutMs) {
+    const name = err instanceof Error ? err.name : "";
+    if (name === "TimeoutError" || name === "AbortError") {
+        return `no response within ${timeoutMs} ms - giving up`;
+    }
+    return String(err);
+}
+async function describeResponseError(response) {
+    let detail = "";
+    try {
+        const body = (await response.text()).trim();
+        if (body)
+            detail = ` - ${truncate(body, ERROR_BODY_LOG_LIMIT)}`;
+    }
+    catch {
+        // Reading the body is best-effort: a body that cannot be read must not
+        // turn a logged warning into a thrown error.
+    }
+    return `${response.status} ${response.statusText}${detail}`;
+}
 // Maps Playwright's more granular statuses down to the three
 // statuses Squally stores (passed | failed | skipped).
 // "timedOut" and "interrupted" both count as failures for reporting purposes.
@@ -31,29 +199,46 @@ function detectCiProvider() {
         return "unknown-ci";
     return null;
 }
-function detectBranch() {
-    if (process.env.GITHUB_REF_NAME)
-        return process.env.GITHUB_REF_NAME;
-    if (process.env.CI_COMMIT_BRANCH)
-        return process.env.CI_COMMIT_BRANCH;
+// Bounded and with stderr suppressed, for the four git fallbacks below. Two
+// separate problems, one fix:
+//   - No timeout meant a hung `git` (e.g. an interactive credential helper
+//     prompting for input that will never come) could block the process
+//     indefinitely with no recovery.
+//   - Inheriting stderr meant a failure printed straight into the customer's
+//     CI log (e.g. "fatal: not a git repository", up to four times per run -
+//     one per detect* function) even though the failure is already handled
+//     gracefully by the caller and never surfaces as a warning. A customer
+//     seeing that text has no way to tell it apart from a real reporter
+//     problem.
+// stdio: ["ignore", "pipe", "ignore"] keeps stdout (the actual value being
+// read) piped back, discards stdin and stderr entirely.
+const GIT_COMMAND_TIMEOUT_MS = 5000;
+function runGitCommand(command) {
     try {
-        return (0, node_child_process_1.execSync)("git rev-parse --abbrev-ref HEAD").toString().trim();
+        return (0, node_child_process_1.execSync)(command, {
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: GIT_COMMAND_TIMEOUT_MS,
+        })
+            .toString()
+            .trim();
     }
     catch {
         return null;
     }
 }
+function detectBranch() {
+    if (process.env.GITHUB_REF_NAME)
+        return process.env.GITHUB_REF_NAME;
+    if (process.env.CI_COMMIT_BRANCH)
+        return process.env.CI_COMMIT_BRANCH;
+    return runGitCommand("git rev-parse --abbrev-ref HEAD");
+}
 function detectCommitSha() {
     if (process.env.GITHUB_SHA)
         return process.env.GITHUB_SHA;
     if (process.env.CI_COMMIT_SHA)
         return process.env.CI_COMMIT_SHA;
-    try {
-        return (0, node_child_process_1.execSync)("git rev-parse HEAD").toString().trim();
-    }
-    catch {
-        return null;
-    }
+    return runGitCommand("git rev-parse HEAD");
 }
 // GitLab CI exposes the full commit message directly (CI_COMMIT_MESSAGE).
 // GitHub Actions has no equivalent env var, so it falls through to the git
@@ -62,12 +247,7 @@ function detectCommitSha() {
 function detectCommitMessage() {
     if (process.env.CI_COMMIT_MESSAGE)
         return process.env.CI_COMMIT_MESSAGE;
-    try {
-        return (0, node_child_process_1.execSync)("git log -1 --pretty=%B").toString().trim();
-    }
-    catch {
-        return null;
-    }
+    return runGitCommand("git log -1 --pretty=%B");
 }
 // GitHub Actions' GITHUB_ACTOR is the user who triggered the workflow run
 // (a username, not necessarily the commit author, but the closest thing
@@ -81,12 +261,74 @@ function detectAuthorName() {
         const match = process.env.CI_COMMIT_AUTHOR.match(/^(.*?)\s*<[^>]*>\s*$/);
         return match ? match[1] : process.env.CI_COMMIT_AUTHOR;
     }
-    try {
-        return (0, node_child_process_1.execSync)("git log -1 --pretty=%an").toString().trim();
+    return runGitCommand("git log -1 --pretty=%an");
+}
+// --- ciRunId (spec sections 1.2, 2.1, 5.3) ----------------------------------
+//
+// This is new in v2 and has no v1 equivalent to imitate: it is what binds
+// several shards of one CI run together into one group (spec section 1.5),
+// and what makes a retried onBegin idempotent (spec section 2.1). It has to
+// be something SHARED across the several separate shard PROCESSES of one CI
+// run, which rules out anything generated inside this process alone for that
+// case - it has to come from the CI environment.
+//
+// One id per provider, chosen because it is shared across a job's shards and
+// distinct across separate runs:
+//   - GitHub Actions: GITHUB_RUN_ID, shared by every matrix/shard job of one
+//     workflow run. GITHUB_RUN_ATTEMPT is appended when present, because a
+//     manual re-run of a failed job REUSES GITHUB_RUN_ID - without the
+//     attempt suffix, re-running a job whose shard had already completed
+//     would immediately hit 409 (append after completion) instead of
+//     starting a fresh, trackable run.
+//   - GitLab CI: CI_PIPELINE_ID, shared by every job in a `parallel:` group -
+//     unlike CI_JOB_ID, which is per-job.
+//   - CircleCI: CIRCLE_WORKFLOW_ID, shared by every job in a workflow -
+//     unlike CIRCLE_BUILD_NUM, which is per-job.
+//
+// No id available (an unrecognised CI provider, or a local run): falls back
+// to a fresh id generated for this process. That id is STABLE across a
+// retried onBegin call within this same process (idempotency still holds
+// locally), but it cannot correlate with a SEPARATE shard process, because
+// there is no shared environment variable to read for those providers. A
+// user on such a provider - or running --shard locally across several
+// invocations - can set SQUALLY_CI_RUN_ID explicitly to restore correlation,
+// the same escape-hatch pattern this file already uses for
+// SAME_REPO_AS_APP/TESTED_REVISION below.
+//
+// env and generateFallback are parameters, not process.env/randomUUID read
+// directly, so this is unit-testable without mocking global state.
+function detectCiRunId(env, generateFallback) {
+    if (env.SQUALLY_CI_RUN_ID)
+        return env.SQUALLY_CI_RUN_ID;
+    if (env.GITHUB_RUN_ID) {
+        return env.GITHUB_RUN_ATTEMPT
+            ? `${env.GITHUB_RUN_ID}-${env.GITHUB_RUN_ATTEMPT}`
+            : env.GITHUB_RUN_ID;
     }
-    catch {
+    if (env.CI_PIPELINE_ID)
+        return env.CI_PIPELINE_ID;
+    if (env.CIRCLE_WORKFLOW_ID)
+        return env.CIRCLE_WORKFLOW_ID;
+    return generateFallback();
+}
+function resolveProjectName(projectSuites) {
+    if (projectSuites.length !== 1)
         return null;
-    }
+    const name = projectSuites[0].project()?.name;
+    return name ? name : null;
+}
+// The per-RESULT counterpart to resolveProjectName above: which project did
+// THIS SPECIFIC test run under, inside a process that may cover several.
+// Playwright's own convention - visible in the app's own reading of
+// titlePath() (squally-app/docs/ingest-v2-spec.md section 5.1) - is that the
+// project name IS what test authors already call their browser/config
+// variant (the FullProject config example in Playwright's own types uses
+// exactly "chromium"/"firefox"/"webkit" as project names), so this reuses
+// that value rather than trying to resolve an underlying browser engine name
+// through a separate, less stable path.
+function resolveBrowserName(test) {
+    const name = test.parent.project()?.name;
+    return name ? truncate(name, V2_FIELD_LIMITS.browserName) : null;
 }
 // --- Flakiness Engine v2 (Phase A): tested application revision ---
 //
@@ -152,20 +394,18 @@ function toPosixPath(p) {
 // via chalk/picocolors) can do the same to stdout/stderr. Stripped here,
 // before anything is ever sent - not server/UI-side - so the raw escape
 // codes never land in the database in the first place, and every later
-// consumer (the existing keyword-based error categorization, the planned
-// AI analysis, a fingerprint cache over normalized error signatures)
-// does not have to strip them again itself.
+// consumer does not have to strip them again itself.
 //
 // Matches the CSI form ANSI color/style codes actually take: an ESC
 // character (code point 27), then an opening bracket, then any run of
 // digits/semicolons, then one letter (e.g. ESC, bracket, 3, 1, m for red).
-// No new dependency (e.g. strip-ansi) for a one-line regex, same reasoning
-// as toPosixPath/the upload worker pool above. Built via String.fromCharCode
-// rather than a hex escape directly in the source: this file has to stay
-// plain, readable ASCII - a raw ESC byte pasted into source code is
-// invisible in most editors/diffs and easy to mistake for empty content.
+// No new dependency (e.g. strip-ansi) for a one-line regex. Built via
+// String.fromCharCode rather than a hex escape directly in the source: this
+// file has to stay plain, readable ASCII - a raw ESC byte pasted into source
+// code is invisible in most editors/diffs and easy to mistake for empty
+// content.
 function stripAnsi(value) {
-    const ansiPattern = new RegExp(String.fromCharCode(27) + String.fromCharCode(92) + "[[0-9;]*[a-zA-Z]", "g");
+    const ansiPattern = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*[a-zA-Z]", "g");
     return value.replace(ansiPattern, "");
 }
 // Playwright captures stdout/stderr as two separate arrays (each internally
@@ -184,6 +424,134 @@ function formatConsoleOutput(result) {
     }
     return lines.length > 0 ? lines.join("\n") : null;
 }
+// --- Console masking (spec section 1.3) -------------------------------------
+//
+// Mirrors squally-app's lib/ingest-v2-core.ts MASK_PATTERNS exactly - same
+// four patterns, same deliberate absence of a fifth. `password=` was dropped
+// there (and is not added here) because it matched ordinary test output far
+// more often than a real secret (an assertion on a validation message about
+// a password field), and masking is not reversible: a false positive
+// destroys the diagnostic value console output exists for in the first
+// place. The app masks again server-side - this copy exists so the token
+// never travels over the wire AT ALL, not merely so it never reaches
+// storage (spec section 1.3: "the field is the one most likely to carry a
+// token").
+const MASK_PATTERNS = [
+    // The token after the scheme, not the word "Bearer" itself - keeping the
+    // scheme is what makes a masked line still readable as an auth header.
+    { pattern: /(Bearer\s+)[A-Za-z0-9\-._~+/]{8,}={0,2}/gi, replace: "$1[redacted]" },
+    { pattern: /\bsk_[A-Za-z0-9_]{8,}/g, replace: "[redacted]" },
+    { pattern: /\bghp_[A-Za-z0-9]{8,}/g, replace: "[redacted]" },
+    { pattern: /\bAKIA[0-9A-Z]{16}\b/g, replace: "[redacted]" },
+];
+function maskSecrets(value) {
+    let masked = value;
+    for (const { pattern, replace } of MASK_PATTERNS) {
+        // Fresh lastIndex per call: these are module-level /g regexes and would
+        // otherwise carry state between inputs (the same bug once landed in
+        // squally-app's own copy of this function).
+        pattern.lastIndex = 0;
+        masked = masked.replace(pattern, replace);
+    }
+    return masked;
+}
+// Console output cap, spec section 1.3 - 16 KB, down from the 20 000
+// CHARACTER limit this file used to enforce for the old flat consoleOutput
+// field. Masks, THEN caps: capping first could cut a token in half and leave
+// a prefix that no longer matches its pattern, storing the first half of a
+// secret. Cutting on a byte boundary can still split a multi-byte character,
+// so the tail is trimmed back to a valid boundary rather than left broken -
+// the exact same logic squally-app applies server-side (belt and braces: the
+// server enforces this regardless of what the reporter already did, but
+// doing it here too means a run never sends more than it needs to).
+const CONSOLE_OUTPUT_MAX_BYTES = 16 * 1024;
+function prepareConsoleOutput(value) {
+    if (value === null)
+        return null;
+    const masked = maskSecrets(value);
+    const bytes = Buffer.from(masked, "utf8");
+    if (bytes.byteLength <= CONSOLE_OUTPUT_MAX_BYTES)
+        return masked;
+    const cut = bytes.subarray(0, CONSOLE_OUTPUT_MAX_BYTES).toString("utf8");
+    return cut.endsWith("�") ? cut.slice(0, -1) : cut;
+}
+// --- errors[] (spec section 1.3) --------------------------------------------
+//
+// Replaces the old errors[0]-only mapping: Playwright supplies an array,
+// v2's wire contract accepts one (up to MAX_ERRORS_PER_RESULT), stored as a
+// child row per element server-side (squally-app's TestResultError).
+//
+// message is REQUIRED on the wire (unlike the old flat errorMessage, which
+// could be null) because a stored error row with no message at all is not
+// useful information. Playwright's own TestError.message is itself OPTIONAL
+// though - it is unset when something other than an Error was thrown (e.g.
+// `throw "a string"`), in which case .value holds what was thrown instead.
+// Falls back to that, then to a fixed string, so this function always
+// produces a message even when Playwright's own error object did not have
+// one to give.
+//
+// Masking is deliberately NOT applied here. The spec scopes masking to
+// console output specifically (section 1.3's own heading), and the app's
+// server-side implementation (squally-app/lib/ingest-v2.ts) only calls its
+// masking function on consoleOutput, nowhere near error text - matching that
+// scope rather than inventing a wider one.
+function mapErrors(errors) {
+    if (errors.length === 0)
+        return undefined;
+    return errors.slice(0, MAX_ERRORS_PER_RESULT).map((error) => {
+        const rawMessage = error.message ?? (error.value !== undefined ? String(error.value) : "Unknown error");
+        const entry = {
+            message: truncate(stripAnsi(rawMessage), FIELD_LIMITS.errorMessage),
+        };
+        if (error.stack)
+            entry.stack = truncate(stripAnsi(error.stack), FIELD_LIMITS.errorStack);
+        // The code-frame snippet Playwright prints can itself carry ANSI
+        // highlighting for the failing line, same reasoning as message/stack.
+        if (error.snippet)
+            entry.snippet = truncate(stripAnsi(error.snippet), MAX_ERROR_SNIPPET);
+        if (error.location) {
+            entry.location = {
+                file: truncate(toPosixPath(node_path_1.default.relative(process.cwd(), error.location.file)), FIELD_LIMITS.filePath),
+                line: error.location.line,
+                column: error.location.column,
+            };
+        }
+        return entry;
+    });
+}
+// --- error-context attachment (spec section 1.2/1.3, "the error-context
+// attachment") -------------------------------------------------------------
+//
+// Playwright attaches a page-state snapshot named "error-context" to a
+// failed attempt (playwright-core's errorContext.js), used by AI debugging
+// tools to understand what the page looked like at the moment of failure.
+// It is either inline (attachment.body) or file-backed (attachment.path),
+// same shape as the screenshot/trace attachments already handled below.
+//
+// Read synchronously, same justification as the existing sizeBytes stat
+// call in onTestEnd: this hook's return value is not awaited by Playwright
+// (Reporter['onTestEnd'] is typed void), so an async read here would race
+// with onEnd() reading collected state before it resolved. These files are
+// small (a text/YAML outline of visible page elements), so a synchronous
+// read costs microseconds, not milliseconds - unlike a screenshot/trace
+// upload, which is genuinely large and stays fully async, uploaded later.
+function readErrorContext(attachment) {
+    if (!attachment)
+        return null;
+    try {
+        const raw = attachment.body !== undefined
+            ? attachment.body.toString("utf8")
+            : attachment.path !== undefined
+                ? (0, node_fs_1.readFileSync)(attachment.path, "utf8")
+                : null;
+        return raw === null ? null : truncate(stripAnsi(raw), V2_FIELD_LIMITS.errorContext);
+    }
+    catch {
+        // File already gone (e.g. cleaned up by a parallel worker) - the same
+        // expected, harmless race the sizeBytes stat below already tolerates.
+        return null;
+    }
+}
 // Presigned upload URLs are valid for 15 minutes (server-side, see
 // squally-app's lib/r2.ts). Uploading fully sequentially could get close to
 // that window for a suite with a very large number of failing/retried
@@ -194,6 +562,28 @@ function formatConsoleOutput(result) {
 // fast enough that even a few hundred artifacts finish in well under 15
 // minutes, bounded enough not to overwhelm a typical CI runner.
 const UPLOAD_CONCURRENCY = 5;
+// Playwright does not let the process end on its own: the runner calls
+// gracefullyCloseAll().then(() => process.exit(code)) (playwright-core's
+// gracefullyProcessExitDoNotHang). process.exit() tears the event loop down
+// immediately, and on Windows that aborts the whole process with
+//   Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src/win/async.c
+// if any of our own I/O is still winding down at that moment - the exit code
+// becomes 127 instead of 0, i.e. a green test run reports as failed.
+//
+// Measured (0.3.0/0.4.0), so the number is not a guess: with the run POST
+// alone the process exits cleanly; from the second request on (presign) it
+// aborts reproducibly. A 0 ms or 10 ms wait does not help, 100 ms survives
+// two requests, and 250 ms survives the full v1 path (ingest -> presign ->
+// upload -> confirm) over repeated runs. Under v2's streaming path there are
+// MORE sequential/concurrent requests over the run's lifetime than v1 ever
+// had, which is exactly why this session's exit-code guard (test/exit-code)
+// was updated rather than assumed to still cover the new path automatically.
+//
+// This is a mitigation, not a cure: it widens the window rather than
+// removing the race, because nothing in Node's public API reports "all my
+// handles are really gone". Do not shrink it without re-running the Windows
+// job in CI - that job exists specifically to catch this.
+const EXIT_DRAIN_MS = 250;
 // No new dependency for this - a fixed-size worker pool that keeps pulling
 // the next item until the list is exhausted is ~10 lines, not worth pulling
 // in e.g. p-limit for.
@@ -226,7 +616,8 @@ function attemptQualifiesForArtifacts(mappedStatus, retryCount) {
 // testName/filePath can contain arbitrary characters, and this key only
 // needs to be unique, not human-readable (it is purely an internal lookup
 // back to the local CollectedArtifact once the server round-trips these
-// identity fields).
+// identity fields). Unchanged from v1 - see the CollectedArtifact comment
+// above for why this stays a 4-part key under v2.
 function artifactKey(testName, filePath, retryCount, type) {
     return [testName, filePath, String(retryCount), type].join(String.fromCharCode(1));
 }
@@ -249,6 +640,55 @@ function confirmReasonMessage(reason) {
 function artifactLabel(type) {
     return type === "screenshot" ? "Screenshot" : "Trace";
 }
+function delay(ms) {
+    return new Promise((resolve) => {
+        const handle = setTimeout(resolve, ms);
+        handle.unref();
+    });
+}
+// Retry-After per RFC 9110: either an integer number of seconds, or an
+// HTTP-date. Returns null (never throws) when the header is absent or
+// unparseable as either form, so the caller can fall back to its own
+// backoff formula.
+function parseRetryAfterMs(headerValue, nowMs) {
+    if (!headerValue)
+        return null;
+    const asSeconds = Number(headerValue);
+    if (Number.isFinite(asSeconds) && asSeconds >= 0)
+        return asSeconds * 1000;
+    const asDate = Date.parse(headerValue);
+    if (!Number.isNaN(asDate))
+        return Math.max(0, asDate - nowMs);
+    return null;
+}
+// retryNumber is 1-indexed (the first retry passes 1, not 0).
+function computeBackoffMs(retryNumber) {
+    return Math.min(RATE_LIMIT_BACKOFF_CAP_MS, RATE_LIMIT_BACKOFF_BASE_MS * 2 ** (retryNumber - 1));
+}
+const TIMED_OUT = Symbol("timed-out");
+// Races a promise against an absolute deadline (a timestamp, not a
+// duration) - absolute so that several sequential awaits inside one drain
+// pass (see drainAndComplete()) can all share the SAME overall budget
+// instead of each getting a fresh one.
+function withDeadline(promise, deadlineMs) {
+    const remaining = Math.max(0, deadlineMs - Date.now());
+    return Promise.race([
+        promise,
+        new Promise((resolve) => {
+            const handle = setTimeout(() => resolve(TIMED_OUT), remaining);
+            handle.unref();
+        }),
+    ]);
+}
+// module-level, not per-instance: spec section 6 says the rules response is
+// "cached in memory for ttlSeconds, per process", and a Playwright process
+// normally constructs exactly one Reporter instance for the run, so this
+// mostly matters as a statement of intent rather than something exercised
+// today - but "per process" is what the spec says, so this is where it
+// lives. v2's reporter only ever FETCHES and stores this; nothing reads it
+// yet (spec: "fetches and ignores... keeps the call path proven before the
+// first behaviour hangs off it").
+let rulesCache = null;
 class SquallyReporter {
     constructor(options = {}) {
         this.apiUrl = "";
@@ -258,8 +698,65 @@ class SquallyReporter {
         // Every onXxx hook checks this first and no-ops if it's false.
         this.enabled = false;
         this.startedAt = new Date();
-        this.results = [];
+        this.ciRunId = "";
+        this.shardIndex = null;
+        this.shardTotal = null;
+        this.projectName = null;
+        this.buffer = [];
         this.artifacts = [];
+        // True once nothing more will ever be sent for this run - a permanent
+        // give-up (402/404/409 on append, or onBegin never getting a runId at
+        // all). onTestEnd stops collecting further results/artifacts once this is
+        // set (see giveUp() below for why that is safe).
+        this.sendingDisabled = false;
+        this.flushTimerHandle = null;
+        this.inFlightFlushes = new Set();
+        // Resolves to the runId once onBegin succeeds, or to null on any permanent
+        // failure (never rejects - every failure path here is a warning, not an
+        // exception, same principle as the rest of this file).
+        this.runIdPromise = Promise.resolve(null);
+        // Set once runIdPromise resolves to a real id - read by onEnd's artifact
+        // upload step, which needs a plain value rather than a promise it would
+        // otherwise have to await a second time.
+        this.runId = null;
+        // onBegin's timestamp is normally the right answer, and under v2 it is the
+        // ONLY answer available at send time: startedAt has to be sent to the
+        // server IMMEDIATELY in onBegin's own request, before a single test has
+        // run - unlike v1, where the whole payload (startedAt included) was built
+        // once at onEnd, after every test's start time was already known.
+        //
+        // v1 corrected this timestamp against the earliest test's own start time,
+        // specifically for `npx playwright merge-reports`, where onBegin fires on
+        // the merging machine minutes or hours after the tests actually ran. That
+        // correction CANNOT be reproduced under v2's streaming model - there is no
+        // moment between "onBegin fired" and "the first test started" at which an
+        // earliest-start value could be known, because onBegin's own network call
+        // has to go out before any test has even begun. This is not a discretionary
+        // simplification; the value the old correction needed does not exist yet
+        // at the point v2 requires startedAt to be sent.
+        //
+        // The one case this used to fix is also the one case v2 no longer supports
+        // for reporting to Squally at all: merge-reports is explicitly unsupported
+        // under ingest v2 (spec section 5.3, closes question 8.8) - ciRunId is now
+        // the one supported sharding path. Dropping the correction therefore loses
+        // nothing for any path v2 actually supports.
+        this.onEnd = async (result) => {
+            if (!this.enabled)
+                return;
+            try {
+                await this.drainAndComplete(result);
+                if (this.runId && this.artifacts.length > 0) {
+                    await this.uploadArtifacts(this.runId);
+                }
+            }
+            finally {
+                await this.dispatcher.close();
+                // See EXIT_DRAIN_MS - closing the dispatcher resolves before the
+                // underlying sockets are fully gone, and Playwright exits the process
+                // the moment onEnd() resolves.
+                await delay(EXIT_DRAIN_MS);
+            }
+        };
         const apiUrl = options.apiUrl ?? process.env.SQUALLY_API_URL;
         const apiKey = options.apiKey ?? process.env.SQUALLY_API_KEY;
         if (!apiUrl || !apiKey) {
@@ -276,28 +773,106 @@ class SquallyReporter {
         this.apiKey = apiKey;
         this.enabled = true;
     }
-    onBegin(_config, _suite) {
+    onBegin(config, suite) {
         if (!this.enabled)
             return;
         this.startedAt = new Date();
+        this.dispatcher = new undici_1.Agent({
+            keepAliveTimeout: 4000,
+            keepAliveMaxTimeout: 4000,
+            headersTimeout: UPLOAD_REQUEST_TIMEOUT_MS,
+            bodyTimeout: UPLOAD_REQUEST_TIMEOUT_MS,
+        });
+        this.ciRunId = truncate(detectCiRunId(process.env, () => (0, node_crypto_1.randomUUID)()), V2_FIELD_LIMITS.ciRunId);
+        // Playwright's shard.current/total are already 1-based, matching the
+        // server's own shardIndex >= 1 constraint (docs/ingest-v2-spec.md
+        // section 1.2) - no adjustment needed.
+        this.shardIndex = config.shard?.current ?? null;
+        this.shardTotal = config.shard?.total ?? null;
+        this.projectName = resolveProjectName(suite.suites);
+        // config.tags is a newer Playwright feature (test tags) than this
+        // package's peer dependency floor (@playwright/test >= 1.30.0) - guarded
+        // rather than assumed present, unlike the well-established fields below
+        // (config.shard, config.workers) which have existed since early
+        // versions and are read unguarded.
+        const tags = Array.isArray(config.tags) ? config.tags : [];
+        this.runTags =
+            tags.length > 0 ? tags.slice(0, MAX_TAGS).map((tag) => truncate(tag, V2_FIELD_LIMITS.tag)) : undefined;
+        this.runConfig = this.resolveRunConfig(config);
+        this.runIdPromise = this.beginRun();
+        void this.fetchRules();
+        this.armFlushTimer();
+    }
+    // config.browsers ({name, version}[]) is deliberately OMITTED here, not
+    // sent as an empty/placeholder array. Getting REAL installed browser
+    // versions would mean either launching each browser type just to query it
+    // (expensive, and a new way for this reporter to fail a customer's CI that
+    // has nothing to do with reporting) or reaching into playwright-core's
+    // private browser-registry internals (undocumented, and liable to break
+    // silently across the wide @playwright/test >= 1.30.0 peer range this
+    // package supports). The field has zero consumers today either way (spec
+    // section 5.2: added "so that later work has real data instead of a
+    // parsed prefix") - sending an invented placeholder version string would
+    // be worse than sending nothing, because it would look like real data to
+    // whatever reads it later. Flagged in this session's report as a decision
+    // the spec left open.
+    resolveRunConfig(config) {
+        return {
+            playwrightVersion: typeof config.version === "string" ? truncate(config.version, V2_FIELD_LIMITS.playwrightVersion) : null,
+            workers: typeof config.workers === "number" ? config.workers : null,
+            os: truncate((0, node_os_1.platform)(), V2_FIELD_LIMITS.os),
+            osVersion: truncate((0, node_os_1.release)(), V2_FIELD_LIMITS.osVersion),
+        };
     }
     onTestEnd(test, result) {
-        if (!this.enabled)
+        if (!this.enabled || this.sendingDisabled)
             return;
-        const error = result.errors[0];
-        const testName = test.titlePath().slice(1).join(" > ");
-        const filePath = toPosixPath(node_path_1.default.relative(process.cwd(), test.location.file));
+        // Truncated HERE, once, not when the payload is built: testName/filePath
+        // are Squally's test identity, and /api/artifacts/presign resolves each
+        // artifact back to a TestResult through exactly these two values plus
+        // retryCount. Cutting them in two places, or cutting them only for the
+        // ingest payload, would make every artifact of a long-named test
+        // unmatchable server-side.
+        //
+        // slice(1), NOT slice(2) - the project name has to stay in the title.
+        // See squally-app/docs/ingest-v2-spec.md section 5.1/5.2: testName is
+        // part of @@unique([projectId, testName, filePath]), and the identity
+        // key is UNCHANGED in v2 (a deliberately conservative decision - see the
+        // spec's own section 5.2). "chromium > a.spec.ts > t" and
+        // "webkit > a.spec.ts > t" stay two independent identities; merging them
+        // would make the same-commit-flip signal treat a browser-specific bug as
+        // proven flakiness across the whole suite at once.
+        const testName = truncate(test.titlePath().slice(1).join(" > "), FIELD_LIMITS.testName);
+        const filePath = truncate(toPosixPath(node_path_1.default.relative(process.cwd(), test.location.file)), FIELD_LIMITS.filePath);
         const status = mapStatus(result.status);
-        this.results.push({
+        // Guarded the same way runTags is above: an older installed Playwright
+        // may not have this field at all.
+        const repeatIndex = typeof test.repeatEachIndex === "number" ? test.repeatEachIndex : 0;
+        const testTags = Array.isArray(test.tags) ? test.tags : [];
+        const errorContextAttachment = result.attachments.find((attachment) => attachment.name === "error-context");
+        this.buffer.push({
             testName,
             filePath,
             status,
-            durationMs: result.duration,
             retryCount: result.retry,
-            errorMessage: error?.message ? stripAnsi(error.message) : null,
-            errorStack: error?.stack ? stripAnsi(error.stack) : null,
-            consoleOutput: formatConsoleOutput(result),
+            repeatIndex,
+            durationMs: result.duration,
+            errors: mapErrors(result.errors),
+            consoleOutput: prepareConsoleOutput(formatConsoleOutput(result)),
+            tags: testTags.length > 0
+                ? testTags.slice(0, MAX_TAGS).map((tag) => truncate(tag, V2_FIELD_LIMITS.tag))
+                : undefined,
+            browserName: resolveBrowserName(test),
+            errorContext: readErrorContext(errorContextAttachment),
         });
+        if (this.buffer.length > MAX_TEST_RESULTS_WARNING && this.buffer.length % MAX_TEST_RESULTS_WARNING === 1) {
+            console.warn(`[squally-reporter] This run has sent well over ${MAX_TEST_RESULTS_WARNING} test results so far. ` +
+                "That usually means retries are configured much higher than intended, or the suite is " +
+                "unusually large - results are still being sent normally.");
+        }
+        if (this.buffer.length >= FLUSH_THRESHOLD_RESULTS) {
+            this.triggerFlush();
+        }
         if (!attemptQualifiesForArtifacts(status, result.retry))
             return;
         for (const attachment of result.attachments) {
@@ -332,98 +907,320 @@ class SquallyReporter {
             });
         }
     }
-    async onEnd(result) {
-        if (!this.enabled)
+    // (decision, spec section 3.2, closes 8.7) At onEnd: flush the remaining
+    // buffer, wait for in-flight batches, then call /complete - bounded by
+    // DRAIN_BUDGET_MS overall, covering waiting for onBegin itself if it has
+    // not resolved yet. On expiry, gives up on draining and calls /complete
+    // anyway with whatever WAS sent - a hung append must not hold the
+    // customer's CI process open indefinitely.
+    //
+    // (deliberate divergence from v1) Once a runId exists, /complete is ALWAYS
+    // called - there is no "this run had zero results, skip reporting it
+    // entirely" special case, unlike v1 (`if (this.results.length === 0)
+    // return;`, guarding the whole of onEnd there). That check cannot be
+    // reproduced here: onBegin already created the run server-side, before a
+    // single test could have told us the eventual count would be zero.
+    // Skipping /complete at this point would not undo the run's existence - it
+    // would leave an already-created run stuck in `running` until the timeout
+    // sweep notices (currently up to 18 hours, see docs/status.md's run-timeout
+    // entry). Completing it immediately with zero results is strictly better: a
+    // short-lived empty run in the dashboard costs less than an
+    // apparently-stuck one for the better part of a day.
+    async drainAndComplete(result) {
+        this.stopFlushTimer();
+        const deadline = Date.now() + DRAIN_BUDGET_MS;
+        const runId = await withDeadline(this.runIdPromise, deadline);
+        if (runId === TIMED_OUT) {
+            console.warn("[squally-reporter] Squally did not confirm the start of this run in time - nothing was sent.");
             return;
-        // A run with 0 test results is meaningless for Squally's flakiness
-        // calculation and would just be dashboard clutter - regardless of why
-        // there were none (npx playwright test --list, an empty testDir, a
-        // --grep filter that matched nothing). Bail out before building/
-        // sending anything.
-        if (this.results.length === 0)
+        }
+        if (runId === null) {
+            // Already warned inside beginRun() - nothing more to say here, and
+            // nothing to complete without a runId.
+            return;
+        }
+        this.runId = runId;
+        if (this.buffer.length > 0)
+            this.triggerFlush();
+        // Result intentionally unused: on expiry we proceed to /complete anyway,
+        // per the decision above - a hung append must not block it.
+        await withDeadline(Promise.allSettled([...this.inFlightFlushes]), deadline);
+        const finalStatus = result.status === "passed" ? "passed" : "failed";
+        await this.completeRun(runId, finalStatus);
+    }
+    armFlushTimer() {
+        if (!this.enabled || this.sendingDisabled)
+            return;
+        const handle = setTimeout(() => {
+            this.triggerFlush();
+            this.armFlushTimer();
+        }, FLUSH_INTERVAL_MS);
+        handle.unref();
+        this.flushTimerHandle = handle;
+    }
+    stopFlushTimer() {
+        if (this.flushTimerHandle) {
+            clearTimeout(this.flushTimerHandle);
+            this.flushTimerHandle = null;
+        }
+    }
+    // Permanent give-up: nothing more will ever be sent for this run. Clears
+    // the UNSENT buffer (those results can never be delivered) and the flush
+    // timer, but deliberately leaves this.artifacts untouched - artifacts
+    // collected BEFORE this point correspond to test results that WERE
+    // already sent and exist server-side, and are still uploaded normally at
+    // onEnd.
+    giveUp() {
+        this.sendingDisabled = true;
+        this.buffer.length = 0;
+        this.stopFlushTimer();
+    }
+    triggerFlush() {
+        const promise = this.flush().catch((err) => {
+            console.warn("[squally-reporter] Unexpected error while sending results:", err);
+        });
+        this.inFlightFlushes.add(promise);
+        void promise.finally(() => this.inFlightFlushes.delete(promise));
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const runId = await this.runIdPromise;
+        if (!runId)
             return;
+        while (this.buffer.length > 0 && !this.sendingDisabled) {
+            const chunk = this.buffer.splice(0, BATCH_MAX_RESULTS);
+            await this.sendBatch(runId, chunk);
+        }
+    }
+    // (spec section 3, the error table) Six outcomes, and they do not all
+    // behave the same way:
+    //   400 (malformed)         - drop THIS batch only, keep going. The spec's
+    //                             own wording for 404/409 explicitly says "stop
+    //                             sending"; 400 does not, and section 3.4 says
+    //                             the server itself "rejects only the batch,
+    //                             not the run" - a local bug producing one bad
+    //                             batch does not mean the next one would also
+    //                             be malformed.
+    //   402 (quota)              - warn once, stop sending for this run.
+    //   404 (unknown runId)      - warn, stop sending for this run.
+    //   409 (already complete)   - warn, stop sending for this run.
+    //   5xx / network error      - already retried once inside requestJson();
+    //                             on final failure, drop this batch, keep
+    //                             going. The spec's table lists no explicit
+    //                             "stop sending" for this case, and a
+    //                             transient server hiccup should not
+    //                             permanently disable reporting for the rest
+    //                             of the run.
+    async sendBatch(runId, batch) {
+        const outcome = await this.requestJson("POST", `${this.apiUrl}/api/ingest/v2/runs/${runId}/results`, { results: batch });
+        if (outcome.kind === "ok")
+            return;
+        if (outcome.kind === "http_error") {
+            switch (outcome.status) {
+                case 400:
+                    console.warn(`[squally-reporter] A batch of ${batch.length} result(s) was rejected: ${outcome.detail} - ` +
+                        "dropping this batch, reporting continues.");
+                    return;
+                case 402:
+                    console.warn(`[squally-reporter] Monthly plan quota exceeded: ${outcome.detail} - no further results will ` +
+                        "be sent for this run. The run will still be marked complete.");
+                    this.giveUp();
+                    return;
+                case 404:
+                    console.warn(`[squally-reporter] Squally no longer has a record of this run: ${outcome.detail} - no ` +
+                        "further results will be sent.");
+                    this.giveUp();
+                    return;
+                case 409:
+                    console.warn(`[squally-reporter] This run was already marked complete on Squally: ${outcome.detail} - no ` +
+                        "further results will be sent.");
+                    this.giveUp();
+                    return;
+                default:
+                    console.warn(`[squally-reporter] Failed to send ${batch.length} result(s) to Squally: ${outcome.status} - ` +
+                        `${outcome.detail} - dropping this batch, reporting continues.`);
+                    return;
+            }
+        }
+        console.warn(`[squally-reporter] Failed to send ${batch.length} result(s) to Squally: ${outcome.detail} - ` +
+            "dropping this batch, reporting continues.");
+    }
+    async beginRun() {
         const resolvedRevision = resolveTestedRevision();
         const payload = {
-            branch: detectBranch(),
-            commitSha: detectCommitSha(),
-            commitMessage: detectCommitMessage(),
-            authorName: detectAuthorName(),
+            ciRunId: this.ciRunId,
+            shardIndex: this.shardIndex,
+            shardTotal: this.shardTotal,
+            projectName: this.projectName,
+            branch: truncateOrNull(detectBranch(), FIELD_LIMITS.branch),
+            commitSha: truncateOrNull(detectCommitSha(), FIELD_LIMITS.commitSha),
+            commitMessage: truncateOrNull(detectCommitMessage(), FIELD_LIMITS.commitMessage),
+            authorName: truncateOrNull(detectAuthorName(), FIELD_LIMITS.authorName),
             ciProvider: detectCiProvider(),
-            status: result.status === "passed" ? "passed" : "failed",
             startedAt: this.startedAt.toISOString(),
-            finishedAt: new Date().toISOString(),
-            testResults: this.results,
-            testedRevision: resolvedRevision?.revision ?? null,
+            testedRevision: truncateOrNull(resolvedRevision?.revision ?? null, FIELD_LIMITS.testedRevision),
             revisionSource: resolvedRevision?.source ?? null,
-            eventType: detectEventType(),
+            eventType: truncateOrNull(detectEventType(), FIELD_LIMITS.eventType),
+            runTags: this.runTags,
+            config: this.runConfig,
+        };
+        const outcome = await this.requestJson("POST", `${this.apiUrl}/api/ingest/v2/runs`, payload);
+        if (outcome.kind === "ok")
+            return outcome.json.runId;
+        // (spec section 7, "New reporter against old app") A 404 here means the
+        // TARGET SERVER does not have the v2 routes at all - an old squally-app.
+        // Cannot happen in production (the app deploys before any reporter that
+        // calls it), but will happen locally while both sides are in
+        // development. Treated as a distinct, permanent condition with its own
+        // message, not retried, and NOT downgraded to a v1 POST - the spec is
+        // explicit that a silent protocol downgrade would make "my streaming
+        // isn't working" undiagnosable. The reporter falls back to sending
+        // nothing for this run instead.
+        if (outcome.kind === "http_error" && outcome.status === 404) {
+            console.warn("[squally-reporter] This Squally instance does not support the v2 ingest API yet (404 on " +
+                "/api/ingest/v2/runs). No results from this run will be sent - update squally-app, or check " +
+                "SQUALLY_API_URL if this is unexpected.");
+        }
+        else {
+            const detail = outcome.kind === "http_error" ? `${outcome.status} - ${outcome.detail}` : outcome.detail;
+            console.error(`[squally-reporter] Failed to start reporting to Squally: ${detail}`);
+        }
+        this.giveUp();
+        return null;
+    }
+    async completeRun(runId, status) {
+        const payload = {
+            shardIndex: this.shardIndex,
+            status,
+            finishedAt: new Date().toISOString(),
         };
-        // Node's global fetch() pools connections through a shared, long-lived
-        // keep-alive dispatcher by default. In a short-lived CLI process like
-        // this reporter, that pooled socket can still be mid-teardown when
-        // Playwright exits the process, which crashes with a libuv assertion on
-        // Windows ("UV_HANDLE_CLOSING", src/win/async.c). Using our own Agent
-        // for this one request and closing it explicitly guarantees no open
-        // handle is left behind by the time onEnd() resolves. Importing fetch
-        // from undici too (not Node's global one) avoids a possible instanceof
-        // mismatch between Node's internal bundled undici and this installed
-        // copy when passing our Agent as the dispatcher.
-        const dispatcher = new undici_1.Agent({ keepAliveTimeout: 1, keepAliveMaxTimeout: 1 });
+        const outcome = await this.requestJson("POST", `${this.apiUrl}/api/ingest/v2/runs/${runId}/complete`, payload);
+        if (outcome.kind !== "ok") {
+            const detail = outcome.kind === "http_error" ? `${outcome.status} - ${outcome.detail}` : outcome.detail;
+            console.error(`[squally-reporter] Failed to mark the run complete on Squally: ${detail}`);
+        }
+    }
+    // (spec section 6) Called once, fired alongside beginRun() rather than
+    // awaited before it - onBegin cannot itself be awaited by Playwright
+    // (Reporter['onBegin'] is typed void), so "before any test runs" is
+    // best-effort here regardless of internal sequencing: tests may already be
+    // executing by the time either promise settles. Deliberately its OWN
+    // request, not routed through requestJson()'s retry machinery: the spec's
+    // failure handling for this call is simpler by design ("on any error,
+    // timeout, or non-200, proceeds with an empty ruleset and warns once") -
+    // a single attempt, no retries, because nothing depends on this succeeding
+    // yet.
+    async fetchRules() {
+        if (rulesCache && rulesCache.expiresAt > Date.now())
+            return;
         try {
-            let runId = null;
+            const response = await (0, undici_1.fetch)(`${this.apiUrl}/api/ingest/v2/rules`, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${this.apiKey}`, "User-Agent": USER_AGENT },
+                dispatcher: this.dispatcher,
+                signal: AbortSignal.timeout(RULES_REQUEST_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                console.warn(`[squally-reporter] Could not fetch quarantine rules from Squally: ` +
+                    `${await describeResponseError(response)} - continuing without them.`);
+                return;
+            }
+            const data = (await response.json());
+            rulesCache = { data, expiresAt: Date.now() + data.ttlSeconds * 1000 };
+        }
+        catch (err) {
+            console.warn("[squally-reporter] Could not fetch quarantine rules from Squally:", describeRequestError(err, RULES_REQUEST_TIMEOUT_MS));
+        }
+    }
+    // Shared low-level request/retry machinery for begin/append/complete.
+    //
+    // Two INDEPENDENT retry policies with separate counters (spec section
+    // 3.2): 429 gets up to RATE_LIMIT_MAX_ATTEMPTS total tries, honouring
+    // Retry-After when present and otherwise backing off exponentially; a 5xx
+    // or network failure gets exactly one retry (SERVER_ERROR_MAX_ATTEMPTS=2
+    // total tries) after a short fixed delay. Any other non-2xx status is
+    // returned immediately, uninterpreted - the CALLER (beginRun/sendBatch/
+    // completeRun) decides what a given status code means for ITS route,
+    // since the same code means different things on different routes (404 on
+    // /runs means "no v2 support"; 404 on /results means "unknown runId").
+    //
+    // Every request here is idempotent server-side (spec section 2:
+    // "Idempotency" - onBegin keyed on ciRunId+shardIndex, append keyed on the
+    // attempt tuple, complete keyed on shardIndex), which is what makes
+    // retrying safely possible in the first place.
+    async requestJson(method, url, body) {
+        let rateLimitAttempts = 0;
+        let serverErrorAttempts = 0;
+        let networkAttempts = 0;
+        for (;;) {
+            let response;
             try {
-                const response = await (0, undici_1.fetch)(`${this.apiUrl}/api/ingest`, {
-                    method: "POST",
+                response = await (0, undici_1.fetch)(url, {
+                    method,
                     headers: {
                         "Content-Type": "application/json",
                         Authorization: `Bearer ${this.apiKey}`,
+                        "User-Agent": USER_AGENT,
                     },
-                    body: JSON.stringify(payload),
-                    dispatcher,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    dispatcher: this.dispatcher,
+                    signal: AbortSignal.timeout(API_REQUEST_TIMEOUT_MS),
                 });
-                if (!response.ok) {
-                    // Never throw here - a failing reporter upload should not fail the
-                    // whole CI run just because the dashboard was unreachable.
-                    console.error(`[squally-reporter] Ingest failed: ${response.status} ${response.statusText}`);
+            }
+            catch (err) {
+                networkAttempts++;
+                if (networkAttempts >= NETWORK_ERROR_MAX_ATTEMPTS) {
+                    return { kind: "network_error", detail: describeRequestError(err, API_REQUEST_TIMEOUT_MS) };
                 }
-                else {
-                    const body = (await response.json());
-                    runId = body.runId ?? null;
+                await delay(SERVER_ERROR_RETRY_DELAY_MS);
+                continue;
+            }
+            if (response.status === 429) {
+                rateLimitAttempts++;
+                if (rateLimitAttempts >= RATE_LIMIT_MAX_ATTEMPTS) {
+                    return { kind: "http_error", status: 429, detail: await describeResponseError(response) };
                 }
+                const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"), Date.now());
+                const waitMs = Math.min(RATE_LIMIT_BACKOFF_CAP_MS, retryAfterMs ?? computeBackoffMs(rateLimitAttempts));
+                await delay(waitMs);
+                continue;
             }
-            catch (err) {
-                console.error("[squally-reporter] Failed to reach Squally API:", err);
+            if (response.status >= 500) {
+                serverErrorAttempts++;
+                if (serverErrorAttempts >= SERVER_ERROR_MAX_ATTEMPTS) {
+                    return { kind: "http_error", status: response.status, detail: await describeResponseError(response) };
+                }
+                await delay(SERVER_ERROR_RETRY_DELAY_MS);
+                continue;
             }
-            // Artifact upload is a separate, best-effort step layered on top of
-            // ingest, never a reason to fail it: it needs a runId (presign looks
-            // TestResults up by runId + identity fields, which only exist once
-            // ingest has actually inserted them), and there's nothing to do if
-            // this run had no failing/retried attempts with a screenshot/trace
-            // attached (attemptQualifiesForArtifacts already filtered that in
-            // onTestEnd) - no reason to make an empty presign call.
-            if (runId && this.artifacts.length > 0) {
-                await this.uploadArtifacts(runId, dispatcher);
+            if (!response.ok) {
+                return { kind: "http_error", status: response.status, detail: await describeResponseError(response) };
+            }
+            try {
+                const json = (await response.json());
+                return { kind: "ok", status: response.status, json };
+            }
+            catch (err) {
+                return { kind: "parse_error", detail: String(err) };
             }
-        }
-        finally {
-            await dispatcher.close();
         }
     }
     // Top-level safety net - presignAndUpload already handles presign/
-    // upload/confirm failures individually (see Aufgabe 5's requirement that
-    // none of this ever affects the test suite's exit code), but this catch
-    // still exists in case something in there throws in a way that wasn't
-    // anticipated. The whole artifact feature must be additive: worst case,
-    // some screenshots/traces don't make it to Squally, but the customer's
-    // CI run itself is never at risk.
-    async uploadArtifacts(runId, dispatcher) {
+    // upload/confirm failures individually, but this catch still exists in
+    // case something in there throws in a way that wasn't anticipated. The
+    // whole artifact feature must be additive: worst case, some screenshots/
+    // traces don't make it to Squally, but the customer's CI run itself is
+    // never at risk.
+    async uploadArtifacts(runId) {
         try {
-            await this.presignAndUpload(runId, dispatcher);
+            await this.presignAndUpload(runId);
         }
         catch (err) {
             console.warn("[squally-reporter] Artifact upload failed unexpectedly:", err);
         }
     }
-    async presignAndUpload(runId, dispatcher) {
+    async presignAndUpload(runId) {
         const presignArtifacts = this.artifacts.map((artifact) => ({
             testName: artifact.testName,
             filePath: artifact.filePath,
@@ -438,19 +1235,22 @@ class SquallyReporter {
                 headers: {
                     "Content-Type": "application/json",
                     Authorization: `Bearer ${this.apiKey}`,
+                    "User-Agent": USER_AGENT,
                 },
                 body: JSON.stringify({ runId, artifacts: presignArtifacts }),
-                dispatcher,
+                dispatcher: this.dispatcher,
+                signal: AbortSignal.timeout(API_REQUEST_TIMEOUT_MS),
             });
             if (!response.ok) {
-                console.warn(`[squally-reporter] Artifact presign failed: ${response.status} ${response.statusText} - skipping artifact upload for this run`);
+                console.warn(`[squally-reporter] Artifact presign failed: ${await describeResponseError(response)}` +
+                    " - skipping artifact upload for this run");
                 return;
             }
             const body = (await response.json());
             presignResults = body.results;
         }
         catch (err) {
-            console.warn("[squally-reporter] Artifact presign request failed:", err);
+            console.warn("[squally-reporter] Artifact presign request failed:", describeRequestError(err, API_REQUEST_TIMEOUT_MS));
             return;
         }
         // Maps a presign result back to the local file it came from -
@@ -482,14 +1282,16 @@ class SquallyReporter {
                 const response = await (0, undici_1.fetch)(uploadUrl, {
                     method: "PUT",
                     body: fileBody,
-                    dispatcher,
+                    dispatcher: this.dispatcher,
+                    signal: AbortSignal.timeout(UPLOAD_REQUEST_TIMEOUT_MS),
                 });
                 if (!response.ok) {
-                    console.warn(`[squally-reporter] Upload failed for ${artifact.type} of '${artifact.testName}': ${response.status} ${response.statusText}`);
+                    console.warn(`[squally-reporter] Upload failed for ${artifact.type} of '${artifact.testName}': ` +
+                        (await describeResponseError(response)));
                 }
             }
             catch (err) {
-                console.warn(`[squally-reporter] Upload failed for ${artifact.type} of '${artifact.testName}':`, err);
+                console.warn(`[squally-reporter] Upload failed for ${artifact.type} of '${artifact.testName}':`, describeRequestError(err, UPLOAD_REQUEST_TIMEOUT_MS));
             }
         });
         // Confirm every artifact that was actually presigned (not the ones
@@ -512,12 +1314,14 @@ class SquallyReporter {
                 headers: {
                     "Content-Type": "application/json",
                     Authorization: `Bearer ${this.apiKey}`,
+                    "User-Agent": USER_AGENT,
                 },
                 body: JSON.stringify({ runId, artifacts: confirmArtifacts }),
-                dispatcher,
+                dispatcher: this.dispatcher,
+                signal: AbortSignal.timeout(API_REQUEST_TIMEOUT_MS),
             });
             if (!response.ok) {
-                console.warn(`[squally-reporter] Artifact confirm failed: ${response.status} ${response.statusText}`);
+                console.warn(`[squally-reporter] Artifact confirm failed: ${await describeResponseError(response)}`);
                 return;
             }
             const body = (await response.json());
@@ -528,8 +1332,29 @@ class SquallyReporter {
             }
         }
         catch (err) {
-            console.warn("[squally-reporter] Artifact confirm request failed:", err);
+            console.warn("[squally-reporter] Artifact confirm request failed:", describeRequestError(err, API_REQUEST_TIMEOUT_MS));
         }
     }
 }
 exports.default = SquallyReporter;
+// Exported for unit tests only (test/unit) - not part of the package's public
+// API surface (see package.json "files": ["dist"], which ships everything in
+// dist regardless, but these are undocumented and may change without notice).
+exports.__internal = {
+    truncate,
+    truncateOrNull,
+    mapStatus,
+    stripAnsi,
+    normalizeRevision,
+    resolveTestedRevision,
+    toPosixPath,
+    detectCiRunId,
+    resolveProjectName,
+    maskSecrets,
+    prepareConsoleOutput,
+    mapErrors,
+    parseRetryAfterMs,
+    computeBackoffMs,
+    attemptQualifiesForArtifacts,
+    artifactKey,
+};