@plune-ai/cli 0.13.0 → 0.14.1

package/dist/reporter-core.cjs

@@ -35,9 +35,13 @@ __export(reporter_core_exports, {
   UNSUPPORTED_VARS: () => UNSUPPORTED_VARS,
   appendBatch: () => appendBatch,
   createClient: () => createClient,
+  errorContextOf: () => errorContextOf,
+  failureOf: () => failureOf,
   readEnv: () => readEnv,
+  repoRootOf: () => repoRootOf,
   resultKey: () => resultKey,
-  startRun: () => startRun
+  startRun: () => startRun,
+  webLink: () => webLink
 });
 module.exports = __toCommonJS(reporter_core_exports);
 
@@ -71,7 +75,39 @@ function loadToken() {
 }
 
 // src/reporter-core/client.ts
+var import_node_http = require("http");
+var import_node_https = require("https");
 var RETRY_DELAYS_MS = [300, 900];
+var IDLE_MS = 3e5;
+function nodeTransport(url, init, idleMs = IDLE_MS) {
+  return new Promise((resolve2, reject) => {
+    const target = new URL(url);
+    const send = target.protocol === "https:" ? import_node_https.request : import_node_http.request;
+    const req = send(target, { method: init.method, headers: init.headers }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk2) => chunks.push(chunk2));
+      res.on("error", reject);
+      res.on("end", () => {
+        const status = res.statusCode ?? 0;
+        const text = Buffer.concat(chunks).toString("utf8");
+        resolve2({
+          ok: status >= 200 && status <= 299,
+          status,
+          headers: {
+            get: (name) => {
+              const value2 = res.headers[name.toLowerCase()];
+              return value2 === void 0 ? null : Array.isArray(value2) ? value2.join(", ") : value2;
+            }
+          },
+          json: async () => JSON.parse(text)
+        });
+      });
+    });
+    req.setTimeout(idleMs, () => req.destroy(new Error(`no answer from ${target.origin} in ${idleMs} ms`)));
+    req.on("error", reject);
+    req.end(init.body);
+  });
+}
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function detailOf(res) {
   try {
@@ -95,7 +131,7 @@ function classify(status) {
   return "other";
 }
 function createClient(opts) {
-  const doFetch = opts.fetchImpl ?? fetch;
+  const doFetch = opts.fetchImpl ?? nodeTransport;
   const wait = opts.wait ?? sleep;
   const base = opts.apiUrl.replace(/\/+$/, "");
   const scrub = (text) => opts.token === "" ? text : text.split(opts.token).join("***");
@@ -123,7 +159,11 @@ function createClient(opts) {
       }
       if (res.ok) {
         if (res.status === 204) return { ok: true, status: res.status, body: void 0 };
-        return { ok: true, status: res.status, body: await res.json() };
+        try {
+          return { ok: true, status: res.status, body: await res.json() };
+        } catch {
+          return { ok: false, kind: "other", status: res.status, detail: "the answer was not JSON" };
+        }
       }
       const detail = scrub(await detailOf(res));
       const kind = classify(res.status);
@@ -238,6 +278,25 @@ function boundKey(key) {
 function boundTitle(title) {
   return title.length <= TITLE_MAX ? title : `${title.slice(0, TITLE_MAX - 1)}\u2026`;
 }
+var BATCH_BYTES = 8 * 1024 * 1024;
+var ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ results: [] }));
+function packed(results) {
+  const out = [];
+  let part = [];
+  let bytes = ENVELOPE_BYTES;
+  for (const result of results) {
+    const size = Buffer.byteLength(JSON.stringify(result));
+    if (part.length > 0 && bytes + 1 + size > BATCH_BYTES) {
+      out.push(part);
+      part = [];
+      bytes = ENVELOPE_BYTES;
+    }
+    bytes += (part.length > 0 ? 1 : 0) + size;
+    part.push(result);
+  }
+  if (part.length > 0) out.push(part);
+  return out;
+}
 function chunk(items, size) {
   const out = [];
   for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
@@ -439,27 +498,35 @@ async function startRun(passed, declared) {
       progress();
       return;
     }
-    const out = await client.post(
-      `/v1/runs/${runId}/results`,
-      { results: submissions }
-    );
-    if (out.ok) {
-      stats.accepted += out.body.counts.accepted ?? 0;
-      stats.duplicate += out.body.counts.duplicate ?? 0;
-      stats.conflict += out.body.counts.conflict ?? 0;
-      stats.rejected += out.body.counts.rejected ?? 0;
-      progress();
-      return;
-    }
-    if (out.kind === "auth") {
-      log('plune: the API token was refused \u2014 run "plune login" with a fresh one.');
-      offline = true;
-    } else if (out.kind === "conflict") {
-      log(`plune: this run is closed \u2014 ${out.detail}`);
-    } else {
-      log(`plune: could not send results (${out.detail || out.kind}).`);
+    for (const part of packed(submissions)) {
+      if (offline) {
+        defer(part);
+        continue;
+      }
+      const out = await client.post(`/v1/runs/${runId}/results`, {
+        results: part
+      });
+      const counts = out.ok ? out.body?.counts : void 0;
+      if (counts !== void 0) {
+        stats.accepted += counts.accepted ?? 0;
+        stats.duplicate += counts.duplicate ?? 0;
+        stats.conflict += counts.conflict ?? 0;
+        stats.rejected += counts.rejected ?? 0;
+        progress();
+        continue;
+      }
+      if (out.ok) {
+        log("plune: could not send results (the answer carried no counts).");
+      } else if (out.kind === "auth") {
+        log('plune: the API token was refused \u2014 run "plune login" with a fresh one.');
+        offline = true;
+      } else if (out.kind === "conflict") {
+        log(`plune: this run is closed \u2014 ${out.detail}`);
+      } else {
+        log(`plune: could not send results (${out.detail || out.kind}).`);
+      }
+      defer(part);
     }
-    defer(submissions);
   }
   function progress() {
     const total = expected?.length ?? 0;
@@ -475,9 +542,12 @@ async function startRun(passed, declared) {
     if (stats.unresolved > 0) parts.push(`${stats.unresolved} with no matching test case`);
     if (stats.offered > 0) parts.push(`${stats.offered} offered for review`);
     if (stats.created > 0) parts.push(`${stats.created} added as cases (trusted source)`);
-    if (stats.deferred > 0) parts.push(`${stats.deferred} written to ${fallbackPath}`);
+    if (stats.deferred > 0) parts.push(`${stats.deferred} not delivered \u2014 written to ${fallbackPath}`);
     if (shortened.size > 0) parts.push(`${shortened.size} test name(s) shortened to fit a key`);
     log(`plune: ${parts.join(" \xB7 ")}`);
+    if (stats.deferred > 0 && process.env["GITHUB_ACTIONS"] === "true") {
+      log(`::warning::${stats.deferred} result(s) were not delivered to Plune \u2014 see the reporting step's log.`);
+    }
   }
   return {
     get runId() {
@@ -537,6 +607,129 @@ function resultKey(testId, retry) {
   const plain = `${testId}#${retry}`;
   return plain.length <= RESULT_KEY_MAX ? plain : `${sha256(testId).slice(0, HASH_CHARS)}#${retry}`;
 }
+
+// src/reporter-core/failure-detail.ts
+var import_node_fs2 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var import_node_util = require("util");
+function failureOf(attempt, home = (0, import_node_os2.homedir)()) {
+  const error = chosen(attempt);
+  const line = error === void 0 ? void 0 : firstLine(machineless(error.text, attempt.repoRoot, home));
+  const headline = line !== void 0 && jsonBytes(line) <= HEADLINE_LIMIT ? line : void 0;
+  const steps = chainOf(attempt.steps);
+  const location = error === void 0 ? void 0 : fromRoot(placeOf(error, attempt.testFile), attempt.repoRoot);
+  const artifacts = attempt.attachments.filter((a) => a.path !== void 0 && !a.name.startsWith("_") && a.contentType !== METADATA_TYPE).map(({ name, contentType }) => ({ name: fileNameOf(name), ...contentType ? { contentType } : {} })).filter((a) => a.name !== "");
+  const ciUrl = webLink(attempt.buildHref);
+  const failure = {
+    ...headline !== void 0 ? { headline } : {},
+    ...steps.length > 0 ? { steps } : {},
+    ...location !== void 0 ? { location } : {},
+    ...artifacts.length > 0 ? { artifacts } : {},
+    ...ciUrl !== void 0 ? { ciUrl } : {}
+  };
+  return Object.keys(failure).length === 0 ? void 0 : failure;
+}
+function repoRootOf(dir, stopAt) {
+  for (let here = (0, import_node_path2.resolve)(dir); ; here = (0, import_node_path2.dirname)(here)) {
+    if ((0, import_node_fs2.existsSync)((0, import_node_path2.join)(here, ".git"))) return here;
+    if (here === stopAt || (0, import_node_path2.dirname)(here) === here) return void 0;
+  }
+}
+function errorContextOf(attempt, home = (0, import_node_os2.homedir)()) {
+  const text = attempt.errors.map((e) => e.text).filter((t) => t !== "").join("\n\n");
+  return cut(machineless(text, attempt.repoRoot, home));
+}
+function machineless(raw, repoRoot, home) {
+  let text = (0, import_node_util.stripVTControlCharacters)(raw).replaceAll("\x1B", "");
+  const root = repoRoot === void 0 ? void 0 : pathIn(repoRoot);
+  if (root !== void 0) text = text.replace(new RegExp(`${PATH_START}${root.source}[\\\\/]+`, root.flags), "");
+  const own = pathIn(home);
+  if (own !== void 0) text = text.replace(new RegExp(`${PATH_START}${own.source}(?![\\w.-])`, own.flags), "~");
+  if (repoRoot === void 0) text = text.replace(ANY_HOME, "~");
+  return text;
+}
+var PATH_START = "(?<![\\w.~%/\\\\-])";
+var TEXT_LIMIT = 524288;
+var HEADLINE_LIMIT = 8 * 1024;
+var jsonBytes = (text) => Buffer.byteLength(JSON.stringify(text)) - 2;
+var ANY_HOME = /(?<=^|[\s'"`(=,[])(?:file:\/\/\/?)?(?:\/home\/|\/Users\/|[A-Za-z]:[\\/]+Users[\\/]+)[^\\/\s'"`:*?<>|]+/g;
+function pathIn(path3) {
+  const parts = path3.split(/[\\/]+/);
+  while (parts.length > 1 && parts.at(-1) === "") parts.pop();
+  if (!parts.some((part) => part !== "" && !/^[A-Za-z]:$/.test(part))) return void 0;
+  const escaped = parts.map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[\\\\/]+");
+  return new RegExp(`(?:file:\\/\\/\\/?)?${escaped}`, /^[A-Za-z]:$/.test(parts[0]) ? "gi" : "g");
+}
+var fileNameOf = (name) => /^(?:file:\/\/|[\\/]|~[\\/]|[A-Za-z]:[\\/])/.test(name) ? name.split(/[\\/]/).pop() ?? "" : name;
+function cut(text) {
+  if (jsonBytes(text) <= TEXT_LIMIT) return text;
+  const lines = text.split("\n");
+  const size = lines.map((line) => jsonBytes(line) + 2);
+  const budget = TEXT_LIMIT - jsonBytes(omitted(lines.length));
+  let used = 0;
+  let head = 0;
+  let tail = lines.length;
+  while (head < tail && used + size[head] <= budget / 2) used += size[head++];
+  while (tail > head && used + size[tail - 1] <= budget) used += size[--tail];
+  return [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n");
+}
+var omitted = (lines) => `\u2026[omitted ${lines} lines]\u2026`;
+var METADATA_TYPE = "application/plune.metadata+json";
+var REPO_RELATIVE = /^(?![A-Za-z][A-Za-z0-9+.-]*:)(?![\\/~])(?!(?:.*[\\/])?\.\.(?:[\\/]|$)).+$/;
+var FRAME = /^\s+at (?:.*? \()?(.+?):(\d+):(\d+)\)?$/;
+var FRAME_MAX = 8192;
+var firstLine = (text) => (0, import_node_util.stripVTControlCharacters)(text).split("\n").map((line) => line.trim()).find((line) => line !== "");
+function chosen({ status, errors }) {
+  if (status === "timedOut") {
+    const timeout = errors.findIndex((e) => firstLine(e.text)?.startsWith("Test timeout of ") === true);
+    if (timeout !== -1 && timeout + 1 < errors.length) return errors[timeout + 1];
+  }
+  return errors[0];
+}
+function chainOf(steps) {
+  const chain = [];
+  for (let failed = steps.find((s) => s.failed); failed !== void 0; failed = failed.steps.find((s) => s.failed)) {
+    chain.push(failed.title);
+  }
+  return chain;
+}
+function placeOf(error, testFile) {
+  const own = normal(testFile);
+  let first;
+  for (const line of (0, import_node_util.stripVTControlCharacters)(error.text).split("\n")) {
+    if (line.length > FRAME_MAX) continue;
+    const frame = FRAME.exec(line);
+    if (frame === null) continue;
+    const place = { file: fileOf(frame[1]), line: Number(frame[2]), column: Number(frame[3]) };
+    if (normal(place.file) === own) return place;
+    if (first === void 0 && !normal(place.file).includes("/node_modules/")) first = place;
+  }
+  return error.location ?? first;
+}
+function fileOf(raw) {
+  if (!raw.startsWith("file://")) return raw;
+  let path3 = raw.slice("file://".length);
+  try {
+    path3 = decodeURIComponent(path3);
+  } catch {
+  }
+  return /^\/[A-Za-z]:\//.test(path3) ? path3.slice(1) : path3;
+}
+var normal = (path3) => import_node_path2.posix.normalize(path3.replace(/\\/g, "/")).replace(/^([a-z]):/, (_, drive) => `${drive.toUpperCase()}:`);
+function fromRoot(place, root) {
+  if (place === void 0 || root === void 0 || !Number.isInteger(place.line) || place.line < 1) return void 0;
+  const base = normal(root).replace(/\/+$/, "");
+  const file = normal(place.file);
+  if (!file.startsWith(`${base}/`)) return void 0;
+  const relative = file.slice(base.length + 1);
+  if (!REPO_RELATIVE.test(relative)) return void 0;
+  const column = place.column !== void 0 && Number.isInteger(place.column) && place.column >= 1 ? place.column : void 0;
+  return column === void 0 ? { file: relative, line: place.line } : { file: relative, line: place.line, column };
+}
+function webLink(href) {
+  return href !== void 0 && /^https?:\/\//i.test(href) && URL.canParse(href) ? href : void 0;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_FALLBACK_PATH,
@@ -544,7 +737,11 @@ function resultKey(testId, retry) {
   UNSUPPORTED_VARS,
   appendBatch,
   createClient,
+  errorContextOf,
+  failureOf,
   readEnv,
+  repoRootOf,
   resultKey,
-  startRun
+  startRun,
+  webLink
 });

package/dist/reporter-core.d.cts

@@ -103,10 +103,80 @@ interface PendingResult {
     specRef?: string;
     execution?: Execution;
     errorContext?: string;
+    /** What failed and where, for a failed attempt (#790); a pass carries none. Built by `failureOf`. */
+    failure?: FailureDetail;
     params?: Record<string, unknown>;
     attachments?: Attachment[];
     assertions?: AssertionRecord[];
 }
+/**
+ * What a failed attempt says about itself on the run page (#790, platform ADR-0002): every field
+ * optional — a field the runner could not supply is absent, never guessed. Nothing here is cut: the
+ * platform bounds the fields after its own cleaning, and a cut before that could halve a credential.
+ */
+interface FailureDetail {
+    /** The first non-empty line of the chosen error, without colour codes. */
+    headline?: string;
+    /** Declared steps (`test.step`), from the outermost to the one that failed. */
+    steps?: string[];
+    /** Where it failed, from the repository root, posix. */
+    location?: {
+        file: string;
+        line: number;
+        column?: number;
+    };
+    /** The files the runner kept for the attempt, by name — the files themselves stay in the CI run. */
+    artifacts?: {
+        name: string;
+        contentType?: string;
+    }[];
+    /** The CI run that produced the report, http(s) only. */
+    ciUrl?: string;
+}
+/** Where a runner says something happened: an absolute file, a line, maybe a column. */
+interface RunnerLocation {
+    file: string;
+    line: number;
+    column?: number;
+}
+/** One error of an attempt, as the runner formats it for a report: the message, the code frame, the
+ * stack's `    at` lines — the form Playwright's JSON report already holds for every error. */
+interface AttemptError {
+    text: string;
+    /** Where the runner says it was thrown. */
+    location?: RunnerLocation;
+}
+/** A step the test declared (`test.step`), with the declared steps inside it — nothing else. */
+interface DeclaredStep {
+    title: string;
+    failed: boolean;
+    steps: DeclaredStep[];
+}
+/**
+ * One failed attempt, as both roads reduce their runner's data to it before anything is derived —
+ * `plune run import` from the JSON report, the adapter from the reporter API (#790 ADR-0001). The same
+ * shape in, so the same detail and the same text out.
+ */
+interface FailedAttempt {
+    /** The runner's word: `timedOut` picks which error the headline comes from. */
+    status: string;
+    /** Every error of the attempt, in order. */
+    errors: AttemptError[];
+    /** The declared steps, outermost first — as the JSON report keeps them. */
+    steps: DeclaredStep[];
+    /** What the runner kept; `path` is what makes one a file. */
+    attachments: {
+        name: string;
+        contentType?: string;
+        path?: string;
+    }[];
+    /** `metadata.ci.buildHref` of the run — the CI run that produced the report. */
+    buildHref?: string;
+    /** The test's own file, absolute. */
+    testFile: string;
+    /** The repository's root on this machine, when one was found above the runner's root dir. */
+    repoRoot?: string;
+}
 /** What a run submission looks like once a key has resolved. Built by the core, never by a caller. */
 interface ResultSubmission extends Omit<PendingResult, 'keys' | 'testCaseId'> {
     testCaseId: string;
@@ -157,7 +227,11 @@ interface RunStats extends SubmitCounts {
      * queue at capacity means "empty it and import again"; nothing else here means that.
      */
     unoffered: number;
-    /** Results written to the fallback file instead of the platform. */
+    /**
+     * Results not delivered, written to the fallback file instead of the platform (#790): a batch
+     * refused for any reason — its size, the network, the token, a closed run — or a result whose keys
+     * the platform could not be asked about. Apart from `rejected` and `unresolved`, which it did answer.
+     */
     deferred: number;
 }
 /** Everything the core needs to talk to a deployment. */
@@ -320,17 +394,34 @@ interface DeferredBatch {
 declare function appendBatch(file: string, batch: DeferredBatch): void;
 
 /**
- * The only thing in this package that talks to the platform.
- *
- * It classifies rather than throws. Every caller has to decide something different about a
- * failure — a batch goes to the fallback file, a rejected token silences the rest of the run, a
- * closed run is a configuration mistake worth naming — and an exception hierarchy would make each
- * of those a `catch` that re-derives what already happened here.
+ * The failure detail of one attempt (#790, ADR-0001 of the feature): what failed, the declared steps
+ * down to it, where, what the runner kept, and the CI run — derived from the attempt both roads
+ * reduce their data to, so `plune run import` and the adapter cannot disagree about it.
  *
- * It also does not log. Anything printed about a failure is printed by the session, which knows
- * the context; keeping the token's only home in this file is what makes AC-12 structural rather
- * than a rule someone has to remember.
+ * Pure: the repository root is found once by the caller (`repoRootOf`) and handed in. Nothing is cut
+ * and nothing is searched for credentials — the platform does both after its own cleaning, and a cut
+ * here could halve a credential it would then not recognise.
+ */
+declare function failureOf(attempt: FailedAttempt, home?: string): FailureDetail | undefined;
+/**
+ * The nearest folder with a `.git` above the runner's root dir — a folder, or the file a worktree
+ * keeps instead. Found once per run by the caller; `stopAt` bounds the walk for a test.
  */
+declare function repoRootOf(dir: string, stopAt?: string): string | undefined;
+/**
+ * `errorContext` for one attempt: every error in order, colour codes gone, the repository as relative
+ * paths and a home folder as `~` — any home folder when the root is unknown, since the report may come
+ * from another machine — and no longer than the CLI's transport limit, cut by whole lines. Nothing is
+ * searched for credentials: the platform does that before its own cut (ADR-0005).
+ */
+declare function errorContextOf(attempt: FailedAttempt, home?: string): string;
+/**
+ * A link only for an address a browser opens as a page — never `file:`, `javascript:` or half a URL.
+ * As the platform checks it: `new URL` alone mends `https:/host` and `https:host` into https, and a
+ * link the platform refuses costs the run's start or the whole batch.
+ */
+declare function webLink(href: string | undefined): string | undefined;
+
 type ClientFailureKind = 
 /** The token was refused. Retrying sends the same token to the same door. */
 'auth'
@@ -371,4 +462,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-export { type AssertionRecord, type Attachment, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, readEnv, resultKey, startRun };
+export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, errorContextOf, failureOf, readEnv, repoRootOf, resultKey, startRun, webLink };

package/dist/reporter-core.d.ts

@@ -103,10 +103,80 @@ interface PendingResult {
     specRef?: string;
     execution?: Execution;
     errorContext?: string;
+    /** What failed and where, for a failed attempt (#790); a pass carries none. Built by `failureOf`. */
+    failure?: FailureDetail;
     params?: Record<string, unknown>;
     attachments?: Attachment[];
     assertions?: AssertionRecord[];
 }
+/**
+ * What a failed attempt says about itself on the run page (#790, platform ADR-0002): every field
+ * optional — a field the runner could not supply is absent, never guessed. Nothing here is cut: the
+ * platform bounds the fields after its own cleaning, and a cut before that could halve a credential.
+ */
+interface FailureDetail {
+    /** The first non-empty line of the chosen error, without colour codes. */
+    headline?: string;
+    /** Declared steps (`test.step`), from the outermost to the one that failed. */
+    steps?: string[];
+    /** Where it failed, from the repository root, posix. */
+    location?: {
+        file: string;
+        line: number;
+        column?: number;
+    };
+    /** The files the runner kept for the attempt, by name — the files themselves stay in the CI run. */
+    artifacts?: {
+        name: string;
+        contentType?: string;
+    }[];
+    /** The CI run that produced the report, http(s) only. */
+    ciUrl?: string;
+}
+/** Where a runner says something happened: an absolute file, a line, maybe a column. */
+interface RunnerLocation {
+    file: string;
+    line: number;
+    column?: number;
+}
+/** One error of an attempt, as the runner formats it for a report: the message, the code frame, the
+ * stack's `    at` lines — the form Playwright's JSON report already holds for every error. */
+interface AttemptError {
+    text: string;
+    /** Where the runner says it was thrown. */
+    location?: RunnerLocation;
+}
+/** A step the test declared (`test.step`), with the declared steps inside it — nothing else. */
+interface DeclaredStep {
+    title: string;
+    failed: boolean;
+    steps: DeclaredStep[];
+}
+/**
+ * One failed attempt, as both roads reduce their runner's data to it before anything is derived —
+ * `plune run import` from the JSON report, the adapter from the reporter API (#790 ADR-0001). The same
+ * shape in, so the same detail and the same text out.
+ */
+interface FailedAttempt {
+    /** The runner's word: `timedOut` picks which error the headline comes from. */
+    status: string;
+    /** Every error of the attempt, in order. */
+    errors: AttemptError[];
+    /** The declared steps, outermost first — as the JSON report keeps them. */
+    steps: DeclaredStep[];
+    /** What the runner kept; `path` is what makes one a file. */
+    attachments: {
+        name: string;
+        contentType?: string;
+        path?: string;
+    }[];
+    /** `metadata.ci.buildHref` of the run — the CI run that produced the report. */
+    buildHref?: string;
+    /** The test's own file, absolute. */
+    testFile: string;
+    /** The repository's root on this machine, when one was found above the runner's root dir. */
+    repoRoot?: string;
+}
 /** What a run submission looks like once a key has resolved. Built by the core, never by a caller. */
 interface ResultSubmission extends Omit<PendingResult, 'keys' | 'testCaseId'> {
     testCaseId: string;
@@ -157,7 +227,11 @@ interface RunStats extends SubmitCounts {
      * queue at capacity means "empty it and import again"; nothing else here means that.
      */
     unoffered: number;
-    /** Results written to the fallback file instead of the platform. */
+    /**
+     * Results not delivered, written to the fallback file instead of the platform (#790): a batch
+     * refused for any reason — its size, the network, the token, a closed run — or a result whose keys
+     * the platform could not be asked about. Apart from `rejected` and `unresolved`, which it did answer.
+     */
     deferred: number;
 }
 /** Everything the core needs to talk to a deployment. */
@@ -320,17 +394,34 @@ interface DeferredBatch {
 declare function appendBatch(file: string, batch: DeferredBatch): void;
 
 /**
- * The only thing in this package that talks to the platform.
- *
- * It classifies rather than throws. Every caller has to decide something different about a
- * failure — a batch goes to the fallback file, a rejected token silences the rest of the run, a
- * closed run is a configuration mistake worth naming — and an exception hierarchy would make each
- * of those a `catch` that re-derives what already happened here.
+ * The failure detail of one attempt (#790, ADR-0001 of the feature): what failed, the declared steps
+ * down to it, where, what the runner kept, and the CI run — derived from the attempt both roads
+ * reduce their data to, so `plune run import` and the adapter cannot disagree about it.
  *
- * It also does not log. Anything printed about a failure is printed by the session, which knows
- * the context; keeping the token's only home in this file is what makes AC-12 structural rather
- * than a rule someone has to remember.
+ * Pure: the repository root is found once by the caller (`repoRootOf`) and handed in. Nothing is cut
+ * and nothing is searched for credentials — the platform does both after its own cleaning, and a cut
+ * here could halve a credential it would then not recognise.
+ */
+declare function failureOf(attempt: FailedAttempt, home?: string): FailureDetail | undefined;
+/**
+ * The nearest folder with a `.git` above the runner's root dir — a folder, or the file a worktree
+ * keeps instead. Found once per run by the caller; `stopAt` bounds the walk for a test.
  */
+declare function repoRootOf(dir: string, stopAt?: string): string | undefined;
+/**
+ * `errorContext` for one attempt: every error in order, colour codes gone, the repository as relative
+ * paths and a home folder as `~` — any home folder when the root is unknown, since the report may come
+ * from another machine — and no longer than the CLI's transport limit, cut by whole lines. Nothing is
+ * searched for credentials: the platform does that before its own cut (ADR-0005).
+ */
+declare function errorContextOf(attempt: FailedAttempt, home?: string): string;
+/**
+ * A link only for an address a browser opens as a page — never `file:`, `javascript:` or half a URL.
+ * As the platform checks it: `new URL` alone mends `https:/host` and `https:host` into https, and a
+ * link the platform refuses costs the run's start or the whole batch.
+ */
+declare function webLink(href: string | undefined): string | undefined;
+
 type ClientFailureKind = 
 /** The token was refused. Retrying sends the same token to the same door. */
 'auth'
@@ -371,4 +462,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-export { type AssertionRecord, type Attachment, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, readEnv, resultKey, startRun };
+export { type AssertionRecord, type Attachment, type AttemptError, type ClientFailureKind, type ClientOptions, type ClientOutcome, DEFAULT_FALLBACK_PATH, type DeclaredStep, type DeferredBatch, type DeferredResult, type EnvSettings, type Execution, type ExpectedEntry, type ExternalKeyKind, type FailedAttempt, type FailureDetail, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, appendBatch, createClient, errorContextOf, failureOf, readEnv, repoRootOf, resultKey, startRun, webLink };