@plune-ai/cli 0.18.0 → 0.20.0

package/README.md

@@ -119,11 +119,11 @@ the last resort, used only when `PLUNE_TOKEN` is set nowhere else. Nothing write
 | `plune init` | Scaffold `plune.yaml`, a sample dataset, and `.env.example`. Flags: `--yes` (non-interactive), `--force`. |
 | `plune login` | Save a [Plune platform](https://plune.ai/platform) API token so `sync` and `ingest` can reach it. The token is **checked against the API before it is saved**, so a wrong one fails here rather than two commands later. Get one at `https://beta.plune.ai` → Account → API tokens. Flags: `--token <token>` (omit to paste it or pipe it via stdin), `--skip-verify` (save without checking, for offline setup). In CI, skip this step: every platform command reads `PLUNE_TOKEN` from the environment first, and the saved login only when it is not set. |
 | `plune logout` | Remove the saved token. |
-| `plune sync` | Upload the latest local run to the platform. Flags: `--file <path>` to send a specific run JSON. |
-| `plune run import <file>` | Turn a **JUnit XML** or **Playwright JSON** report, or an **Allure `allure-results` folder**, into a run in Plune. Needs no provider key — nothing is generated. Flags: `--format junit\|playwright-json\|allure` (detected from the file when omitted; a folder is Allure), `--key <externalKey>` to land several reports in one run (with `PLUNE_SHARED_RUN=1` — see below), `--create` to offer unmatched tests to the review queue, `--fail-on-missing-attachments` to exit 1 when a file a JUnit report names with `[[ATTACHMENT\|path]]`, or an Allure result names as a `source`, is not there (the results are sent either way). |
+| `plune sync` | Upload the latest local run to the platform. Flags: `--file <path>` to send a specific run JSON, `--fail-on-failures` to read the run's summary back once after the upload and exit with [the gate](#a-release-gate---fail-on-failures)'s code. |
+| `plune run import <file>` | Turn a **JUnit XML** or **Playwright JSON** report, or an **Allure `allure-results` folder**, into a run in Plune. Needs no provider key — nothing is generated. Flags: `--format junit\|playwright-json\|allure` (detected from the file when omitted; a folder is Allure), `--key <externalKey>` to land several reports in one run (with `PLUNE_SHARED_RUN=1` — see below), `--create` to offer unmatched tests to the review queue, `--fail-on-missing-attachments` to exit 1 when a file a JUnit report names with `[[ATTACHMENT\|path]]`, or an Allure result names as a `source`, is not there (the results are sent either way), `--fail-on-failures` to exit with [the gate](#a-release-gate---fail-on-failures)'s code on the summary the platform froze when this import finished the run. |
 | `plune run start` | Open a platform run — or join the one already carrying `--key` — and print its id. Flags: `--key <externalKey>` (generated when absent), `--json` for one machine-readable line. |
-| `plune run finish <id>` | Close a platform run. This is what the reporter tells you to do for a run it had to leave open. Flags: `--terminate` to record it as cut short, `--reason <text>`. |
-| `plune run exec -- <command>` | Open a run, run the command inside it, close the run — and exit with whatever the command returned. Sets `PLUNE_SHARED_RUN` for you, so anything reporting inside joins that run. Flags: `--key <externalKey>`. |
+| `plune run finish <id>` | Close a platform run. This is what the reporter tells you to do for a run it had to leave open. Flags: `--terminate` to record it as cut short, `--reason <text>`, `--fail-on-failures` to exit with [the gate](#a-release-gate---fail-on-failures)'s code on the summary the platform froze. |
+| `plune run exec -- <command>` | Open a run, run the command inside it, close the run — and exit with whatever the command returned. Sets `PLUNE_SHARED_RUN` for you, so anything reporting inside joins that run. Flags: `--key <externalKey>`, `--fail-on-failures` to exit with [the gate](#a-release-gate---fail-on-failures)'s code instead — or with the command's own when no result reached the run. |
 | `plune run delete <id>` | Delete a run and everything it produced — its results and the review-queue entries it raised. Approved test cases and the audit log stay. **Recoverable for 30 days** (an owner of the project can put it back from Settings → Bin), then gone for good. No prompt: it is your data, and this command belongs in scripts. |
 | `plune run report` | Replay `.plune/pending-results.jsonl` — send what the reporter could not. The lines of one reporter run go back as one run, with the commit and branch the reporter recorded. Once every result has gone the file is renamed to `pending-results.<time>.sent.jsonl`; if anything did not go, it stays as it was. Flags: `--file <path>`. |
 | `plune ingest [dir]` | Record a [Cairn](https://github.com/plune-ai/cairn) run in Plune. Omit `[dir]` for the newest run under `./runs`, or name the directory holding `report.json`. Generated cases arrive as **review proposals** — nothing is created until a person approves it. |
@@ -135,6 +135,24 @@ Global flags: `-c, --config <path>` · `-v, --verbose` · `--no-color`.
 
 **Exit codes:** `0` everything passed · `1` an assertion failed · `2` configuration or execution error · `3` `pull` refused to overwrite uncommitted changes · `4` `push` had refusals.
 
+### A release gate: `--fail-on-failures`
+
+`plune run finish`, `plune run exec`, `plune run import` and `plune sync` take `--fail-on-failures`. The exit
+code is then the platform's verdict on the run, not the runner's: the summary the platform froze at `finish`
+(for `sync`, one `GET /v1/runs/:id/summary` after the upload). The platform counts a muted case's failure under
+`muted`, so a mute set in Plune is honoured without the CLI knowing about it.
+
+| The run | Exit |
+| ------- | ---- |
+| a `failed` or `broken` result that is not muted | `1` |
+| an expected case that never reported (`notRun`): a dead shard is not green | `1` |
+| only `passed`, `blocked`, `skipped` and muted failures | `0` |
+| no verdict: the platform could not be reached, the finish was refused, the run was left open or terminated | `1` |
+| `run exec` where no result reached the run and nothing was expected of it | the command's own code |
+
+Without the flag every command exits as it always did. `plune run` (local evals) is not affected: it stays the
+raw local signal and works offline.
+
 ## Already running tests? Bring the results in
 
 Everything above generates checks, which is why it needs a provider key. If you already have a

package/dist/cli.cjs

@@ -3306,21 +3306,26 @@ async function startRun(passed, declared2) {
     },
     flush,
     async finish(reason) {
-      if (done) return;
+      if (done) return void 0;
       done = true;
       await flush();
       await offer();
+      let frozen;
       if (runId !== null && !offline) {
         const out = await client.post(`/v1/runs/${runId}/events`, {
           event: "finish",
           ...reason !== void 0 ? { reason } : {}
         });
         if (!out.ok) log(`plune: could not close run ${runId} (${out.detail || out.kind}).`);
-        else if (typeof out.body?.detached === "number" && out.body.detached > 0) {
-          log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+        else {
+          frozen = out.body?.summary ?? void 0;
+          if (typeof out.body?.detached === "number" && out.body.detached > 0) {
+            log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+          }
         }
       }
       summarise();
+      return frozen;
     },
     async leaveOpen() {
       if (done) return;
@@ -3398,6 +3403,28 @@ var init_session = __esm({
   }
 });
 
+// src/cli/gate.ts
+function gateExit(verdict, runnerCode) {
+  if (verdict?.statusEvent === "terminated") {
+    return { code: 1, line: "plune: gate failed \u2014 the run was terminated, so it has no verdict to pass on." };
+  }
+  const counts = verdict?.counts;
+  if (counts == null) return { code: 1, line: "plune: gate failed \u2014 no verdict from the platform, and no verdict is no pass." };
+  const n = (status) => counts[status] ?? 0;
+  const notRun = verdict?.notRun?.length ?? 0;
+  if (runnerCode !== void 0 && notRun === 0 && Object.values(counts).every((k) => !k)) {
+    return { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` };
+  }
+  const said = `${n("failed")} failed \xB7 ${n("broken")} broken \xB7 ${notRun} not run \xB7 ${n("muted")} muted`;
+  return n("failed") + n("broken") > 0 || notRun > 0 ? { code: 1, line: `plune: gate failed \u2014 ${said}` } : { code: 0, line: `plune: gate passed \u2014 ${said}` };
+}
+var init_gate = __esm({
+  "src/cli/gate.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
 // src/cli/commands/run-lifecycle.ts
 var run_lifecycle_exports = {};
 __export(run_lifecycle_exports, {
@@ -3455,7 +3482,7 @@ async function handleRunStart(options = {}) {
   }
   return result;
 }
-async function handleRunFinish(id, options = {}) {
+async function handleRunFinish(id, options = {}, runnerCode) {
   const { client, write } = connect(options);
   const event = options.terminate === true ? "terminate" : "finish";
   const out = await client.post(`/v1/runs/${id}/events`, {
@@ -3468,6 +3495,11 @@ async function handleRunFinish(id, options = {}) {
     );
   }
   write(`Run ${id} ${event === "finish" ? "finished" : "terminated"}.`);
+  if (options.failOnFailures !== true) return runnerCode ?? 0;
+  const summary = out.body?.summary;
+  const gate = gateExit({ statusEvent: out.body?.run?.statusEvent, counts: summary?.counts, notRun: summary?.notRun }, runnerCode);
+  write(gate.line);
+  return gate.code;
 }
 async function handleRunDelete(id, options = {}) {
   const { client, write } = connect(options);
@@ -3499,8 +3531,7 @@ async function handleRunExec(options) {
     child.on("close", (exitCode) => resolve9(exitCode ?? 1));
     child.on("error", () => resolve9(1));
   });
-  await handleRunFinish(run.id, options);
-  return code;
+  return handleRunFinish(run.id, options, code);
 }
 async function handleRunReport(options = {}) {
   const file = options.file ?? DEFAULT_FALLBACK_PATH;
@@ -3596,6 +3627,7 @@ var init_run_lifecycle = __esm({
     init_env2();
     init_fallback();
     init_session();
+    init_gate();
     NoTokenError = class extends Error {
       constructor() {
         super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
@@ -4469,8 +4501,9 @@ async function handleRunImport(options) {
     results.map((r) => r.keys)
   );
   for (const result2 of results) await session.add(result2);
+  let frozen;
   if (env.keepOpen) await session.leaveOpen();
-  else await session.finish();
+  else frozen = await session.finish();
   const stats = session.stats;
   const result = {
     runId: session.runId,
@@ -4499,6 +4532,14 @@ async function handleRunImport(options) {
     offering: options.create === true
   };
   for (const line of describe(result, apiUrl)) write(line);
+  if (options.failOnFailures === true) {
+    if (env.keepOpen) {
+      write("plune: the run is left open for the jobs still reporting, so there is no verdict yet \u2014 gate on the step that finishes it.");
+    }
+    const gate = gateExit(frozen);
+    write(gate.line);
+    result.gate = gate.code;
+  }
   return result;
 }
 function runUrl2(apiUrl, id) {
@@ -4565,6 +4606,7 @@ var init_run_import = __esm({
     init_run_lifecycle();
     init_api_url();
     init_credentials();
+    init_gate();
     init_env2();
     NEXT = {
       queue: "the review queue is full. Approve or reject what is waiting, then import this report again to offer the rest.",
@@ -5220,7 +5262,18 @@ async function handleSync(deps = {}) {
   }
   const body = await res.json().catch(() => ({}));
   const id = typeof body.id === "string" ? body.id : "";
-  return { id, url: `${endpoint}/${id}` };
+  const result = { id, url: `${endpoint}/${id}` };
+  if (deps.failOnFailures === true) result.gate = gateExit(await readVerdict(doFetch, `${endpoint}/${id}/summary`, token));
+  return result;
+}
+async function readVerdict(doFetch, url, token) {
+  try {
+    const res = await doFetch(url, { method: "GET", headers: { authorization: `Bearer ${token}` } });
+    const body = await res.json().catch(() => void 0);
+    return res.ok ? { statusEvent: body?.run?.statusEvent, counts: body?.counts, notRun: body?.notRun } : void 0;
+  } catch {
+    return void 0;
+  }
 }
 function reportSyncFailure(err, write) {
   if (err instanceof NotLoggedInError || err instanceof TokenRejectedError2 || err instanceof SyncFileError) {
@@ -5243,6 +5296,7 @@ var init_sync = __esm({
     init_run_result_schema();
     init_api_url();
     init_credentials();
+    init_gate();
     NotLoggedInError = class extends Error {
       constructor() {
         super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
@@ -5314,7 +5368,8 @@ async function defaultReadEvidence(dir) {
   if (!Array.isArray(raw)) return void 0;
   return raw.map((r) => {
     const rec = asRecord(r);
-    return { name: str(rec["name"]), passed: rec["passed"] === true };
+    const error = str(rec["error"]);
+    return { name: str(rec["name"]), passed: rec["passed"] === true, ...error !== "" ? { error } : {} };
   });
 }
 function casesFromDesign(report) {
@@ -5373,7 +5428,7 @@ async function readCairnRun(dir, deps = {}) {
     const verdicts = /* @__PURE__ */ new Map();
     for (const e of evidence ?? []) {
       if (verdicts.has(e.name)) throw new CairnEvidenceAmbiguousError(e.name);
-      verdicts.set(e.name, e.passed ? "passed" : "failed");
+      verdicts.set(e.name, e.error !== void 0 ? "blocked" : e.passed ? "passed" : "failed");
     }
     cases = casesFromApi(report, verdicts);
   } else {
@@ -5907,6 +5962,7 @@ function createProgram() {
     process.exit(1);
   };
   const verboseOf = (command) => command.optsWithGlobals().verbose === true;
+  const FAIL_ON_FAILURES = "Exit with the platform's verdict on the run: 1 on a failed or broken result (muted ones do not count), on an expected case that never ran, or when there is no verdict at all";
   runCommand.command("start").description("Open a platform run (or join one already carrying the key) and print its id").option("--key <externalKey>", "The key several processes share; generated when absent").option("--json", "Print one machine-readable line instead of prose", false).action(async (options, command) => {
     try {
       const { handleRunStart: handleRunStart2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
@@ -5918,14 +5974,16 @@ function createProgram() {
       await failRunCommand(err, verboseOf(command));
     }
   });
-  runCommand.command("finish").argument("<id>", "The run to close").description("Close a platform run \u2014 what the reporter tells you to do for a run left open").option("--terminate", "Record the run as cut short rather than finished", false).option("--reason <text>", "Why, for a terminated run").action(
+  runCommand.command("finish").argument("<id>", "The run to close").description("Close a platform run \u2014 what the reporter tells you to do for a run left open").option("--terminate", "Record the run as cut short rather than finished", false).option("--reason <text>", "Why, for a terminated run").option("--fail-on-failures", FAIL_ON_FAILURES, false).action(
     async (id, options, command) => {
       try {
         const { handleRunFinish: handleRunFinish2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
-        await handleRunFinish2(id, {
+        const code = await handleRunFinish2(id, {
           terminate: options.terminate,
-          ...options.reason !== void 0 ? { reason: options.reason } : {}
+          ...options.reason !== void 0 ? { reason: options.reason } : {},
+          ...options.failOnFailures ? { failOnFailures: true } : {}
         });
+        if (options.failOnFailures) process.exitCode = code;
       } catch (err) {
         await failRunCommand(err, verboseOf(command));
       }
@@ -5933,12 +5991,13 @@ function createProgram() {
   );
   runCommand.command("exec").argument("<command...>", "The command to run inside the run, after `--`").description(
     "Open a run, run a command inside it, close the run \u2014 whatever the command returns"
-  ).option("--key <externalKey>", "The key several processes share; generated when absent").action(async (argv, options, command) => {
+  ).option("--key <externalKey>", "The key several processes share; generated when absent").option("--fail-on-failures", `${FAIL_ON_FAILURES}; the command's own exit code when no result reached the run`, false).action(async (argv, options, command) => {
     try {
       const { handleRunExec: handleRunExec2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
       process.exitCode = await handleRunExec2({
         argv,
-        ...options.key !== void 0 ? { key: options.key } : {}
+        ...options.key !== void 0 ? { key: options.key } : {},
+        ...options.failOnFailures ? { failOnFailures: true } : {}
       });
     } catch (err) {
       await failRunCommand(err, verboseOf(command));
@@ -5967,7 +6026,7 @@ function createProgram() {
     "--fail-on-missing-attachments",
     "Exit 1 when a file the report names ([[ATTACHMENT|path]] in JUnit, a source in allure-results) is not there; the results are sent either way",
     false
-  ).action(
+  ).option("--fail-on-failures", FAIL_ON_FAILURES, false).action(
     async (file, options, command) => {
       const [
         { handleRunImport: handleRunImport2 },
@@ -5991,9 +6050,11 @@ function createProgram() {
           file,
           ...format !== void 0 ? { format } : {},
           ...options.key !== void 0 ? { key: options.key } : {},
-          ...options.create ? { create: true } : {}
+          ...options.create ? { create: true } : {},
+          ...options.failOnFailures ? { failOnFailures: true } : {}
         });
         if (options.failOnMissingAttachments && imported.missingAttachments.length > 0) process.exitCode = 1;
+        if (imported.gate === 1) process.exitCode = 1;
       } catch (err) {
         if (err instanceof UnknownFormatError2 || err instanceof XmlParseError2 || err instanceof JsonReportError2 || err instanceof AllureReportError2) {
           process.stderr.write(err.message + "\n");
@@ -6103,18 +6164,24 @@ function createProgram() {
       failUnexpected(err, verbose);
     }
   });
-  program.command("sync").description("Upload your latest local run to the Plune platform (POST /v1/runs)").option("--file <path>", "Sync a specific run JSON instead of .plune/last-run.json").action(async (options, command) => {
+  program.command("sync").description("Upload your latest local run to the Plune platform (POST /v1/runs)").option("--file <path>", "Sync a specific run JSON instead of .plune/last-run.json").option("--fail-on-failures", `${FAIL_ON_FAILURES}; read with one GET of the run's summary after the upload`, false).action(async (options, command) => {
     const globals = command.optsWithGlobals();
     const verbose = globals.verbose === true;
     const { handleSync: handleSync2, reportSyncFailure: reportSyncFailure2 } = await Promise.resolve().then(() => (init_sync(), sync_exports));
     const cwd = globals.config !== void 0 ? (0, import_node_path4.dirname)((0, import_node_path4.resolve)(globals.config)) : process.cwd();
     try {
-      const { id, url } = await handleSync2({
+      const { id, url, gate } = await handleSync2({
         cwd,
-        ...options.file !== void 0 ? { file: options.file } : {}
+        ...options.file !== void 0 ? { file: options.file } : {},
+        ...options.failOnFailures ? { failOnFailures: true } : {}
       });
       process.stdout.write(`Synced run ${id} \u2192 ${url}
 `);
+      if (gate !== void 0) {
+        process.stdout.write(`${gate.line}
+`);
+        process.exitCode = gate.code;
+      }
     } catch (err) {
       const code = reportSyncFailure2(err, (s) => process.stderr.write(s));
       if (code !== null) {

package/dist/index.cjs

@@ -1703,6 +1703,22 @@ function loadToken() {
   }
 }
 
+// src/cli/gate.ts
+function gateExit(verdict, runnerCode) {
+  if (verdict?.statusEvent === "terminated") {
+    return { code: 1, line: "plune: gate failed \u2014 the run was terminated, so it has no verdict to pass on." };
+  }
+  const counts = verdict?.counts;
+  if (counts == null) return { code: 1, line: "plune: gate failed \u2014 no verdict from the platform, and no verdict is no pass." };
+  const n = (status) => counts[status] ?? 0;
+  const notRun = verdict?.notRun?.length ?? 0;
+  if (runnerCode !== void 0 && notRun === 0 && Object.values(counts).every((k) => !k)) {
+    return { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` };
+  }
+  const said = `${n("failed")} failed \xB7 ${n("broken")} broken \xB7 ${notRun} not run \xB7 ${n("muted")} muted`;
+  return n("failed") + n("broken") > 0 || notRun > 0 ? { code: 1, line: `plune: gate failed \u2014 ${said}` } : { code: 0, line: `plune: gate passed \u2014 ${said}` };
+}
+
 // src/cli/commands/sync.ts
 var NotLoggedInError = class extends Error {
   constructor() {
@@ -1795,7 +1811,18 @@ async function handleSync(deps = {}) {
   }
   const body = await res.json().catch(() => ({}));
   const id = typeof body.id === "string" ? body.id : "";
-  return { id, url: `${endpoint}/${id}` };
+  const result = { id, url: `${endpoint}/${id}` };
+  if (deps.failOnFailures === true) result.gate = gateExit(await readVerdict(doFetch, `${endpoint}/${id}/summary`, token));
+  return result;
+}
+async function readVerdict(doFetch, url, token) {
+  try {
+    const res = await doFetch(url, { method: "GET", headers: { authorization: `Bearer ${token}` } });
+    const body = await res.json().catch(() => void 0);
+    return res.ok ? { statusEvent: body?.run?.statusEvent, counts: body?.counts, notRun: body?.notRun } : void 0;
+  } catch {
+    return void 0;
+  }
 }
 function reportSyncFailure(err, write) {
   if (err instanceof NotLoggedInError || err instanceof TokenRejectedError || err instanceof SyncFileError) {
@@ -1883,7 +1910,8 @@ async function defaultReadEvidence(dir) {
   if (!Array.isArray(raw)) return void 0;
   return raw.map((r) => {
     const rec = asRecord(r);
-    return { name: str(rec["name"]), passed: rec["passed"] === true };
+    const error = str(rec["error"]);
+    return { name: str(rec["name"]), passed: rec["passed"] === true, ...error !== "" ? { error } : {} };
   });
 }
 function casesFromDesign(report) {
@@ -1942,7 +1970,7 @@ async function readCairnRun(dir, deps = {}) {
     const verdicts = /* @__PURE__ */ new Map();
     for (const e of evidence ?? []) {
       if (verdicts.has(e.name)) throw new CairnEvidenceAmbiguousError(e.name);
-      verdicts.set(e.name, e.passed ? "passed" : "failed");
+      verdicts.set(e.name, e.error !== void 0 ? "blocked" : e.passed ? "passed" : "failed");
     }
     cases = casesFromApi(report, verdicts);
   } else {

package/dist/index.d.cts

@@ -315,12 +315,19 @@ interface SyncDeps {
     loadToken?: () => string | null;
     /** HTTP transport (injected in tests — e.g. a real Hono app's `request`). Defaults to global `fetch`. */
     fetchImpl?: typeof fetch;
+    /** `--fail-on-failures`: read the run's summary back once after the upload and judge it (plune#1247). */
+    failOnFailures?: boolean;
 }
 interface SyncResult {
     /** Server-assigned run id. */
     id: string;
     /** The `GET /v1/runs/:id` URL where the uploaded run can be read back. */
     url: string;
+    /** The exit code `--fail-on-failures` asks for and the line that says why; absent without the flag. */
+    gate?: {
+        code: number;
+        line: string;
+    };
 }
 /**
  * Upload the latest (or `--file`) local run to `POST {apiUrl}/v1/runs` with the stored Bearer token.
@@ -645,7 +652,12 @@ declare function formatIngestResult(r: IngestResult): string;
 declare const INGEST_SCHEMA_VERSION = 1;
 type CairnRunMode = 'explore' | 'design' | 'api';
 type CairnExecution = 'auto' | 'manual';
-type CairnVerdict = 'passed' | 'failed';
+/**
+ * `blocked` (plune-ai/plune#1327): the case's request got no answer — Cairn's evidence records a transport error
+ * after the retries — so the product never said anything either way. Sent as `failed`, it blamed the product for an
+ * unreachable target. Needs a platform that accepts it (plune-ai/plune#1330); an older one refuses the payload.
+ */
+type CairnVerdict = 'passed' | 'failed' | 'blocked';
 interface CairnIngestCase {
     stableId: string;
     title: string;
@@ -669,6 +681,8 @@ interface CairnIngestPayload {
 interface EvidenceRecord {
     name: string;
     passed: boolean;
+    /** Cairn's transport error, when the request got no response after the retries. */
+    error?: string;
 }
 interface ReadCairnRunDeps {
     /** Injected for tests; returns `undefined` when the run executed nothing and wrote no evidence. */

package/dist/index.d.ts

@@ -315,12 +315,19 @@ interface SyncDeps {
     loadToken?: () => string | null;
     /** HTTP transport (injected in tests — e.g. a real Hono app's `request`). Defaults to global `fetch`. */
     fetchImpl?: typeof fetch;
+    /** `--fail-on-failures`: read the run's summary back once after the upload and judge it (plune#1247). */
+    failOnFailures?: boolean;
 }
 interface SyncResult {
     /** Server-assigned run id. */
     id: string;
     /** The `GET /v1/runs/:id` URL where the uploaded run can be read back. */
     url: string;
+    /** The exit code `--fail-on-failures` asks for and the line that says why; absent without the flag. */
+    gate?: {
+        code: number;
+        line: string;
+    };
 }
 /**
  * Upload the latest (or `--file`) local run to `POST {apiUrl}/v1/runs` with the stored Bearer token.
@@ -645,7 +652,12 @@ declare function formatIngestResult(r: IngestResult): string;
 declare const INGEST_SCHEMA_VERSION = 1;
 type CairnRunMode = 'explore' | 'design' | 'api';
 type CairnExecution = 'auto' | 'manual';
-type CairnVerdict = 'passed' | 'failed';
+/**
+ * `blocked` (plune-ai/plune#1327): the case's request got no answer — Cairn's evidence records a transport error
+ * after the retries — so the product never said anything either way. Sent as `failed`, it blamed the product for an
+ * unreachable target. Needs a platform that accepts it (plune-ai/plune#1330); an older one refuses the payload.
+ */
+type CairnVerdict = 'passed' | 'failed' | 'blocked';
 interface CairnIngestCase {
     stableId: string;
     title: string;
@@ -669,6 +681,8 @@ interface CairnIngestPayload {
 interface EvidenceRecord {
     name: string;
     passed: boolean;
+    /** Cairn's transport error, when the request got no response after the retries. */
+    error?: string;
 }
 interface ReadCairnRunDeps {
     /** Injected for tests; returns `undefined` when the run executed nothing and wrote no evidence. */

package/dist/index.js

@@ -1647,6 +1647,22 @@ function loadToken() {
   }
 }
 
+// src/cli/gate.ts
+function gateExit(verdict, runnerCode) {
+  if (verdict?.statusEvent === "terminated") {
+    return { code: 1, line: "plune: gate failed \u2014 the run was terminated, so it has no verdict to pass on." };
+  }
+  const counts = verdict?.counts;
+  if (counts == null) return { code: 1, line: "plune: gate failed \u2014 no verdict from the platform, and no verdict is no pass." };
+  const n = (status) => counts[status] ?? 0;
+  const notRun = verdict?.notRun?.length ?? 0;
+  if (runnerCode !== void 0 && notRun === 0 && Object.values(counts).every((k) => !k)) {
+    return { code: runnerCode, line: `plune: gate \u2014 no result reached the run, so the exit code is the command's own (${runnerCode}).` };
+  }
+  const said = `${n("failed")} failed \xB7 ${n("broken")} broken \xB7 ${notRun} not run \xB7 ${n("muted")} muted`;
+  return n("failed") + n("broken") > 0 || notRun > 0 ? { code: 1, line: `plune: gate failed \u2014 ${said}` } : { code: 0, line: `plune: gate passed \u2014 ${said}` };
+}
+
 // src/cli/commands/sync.ts
 var NotLoggedInError = class extends Error {
   constructor() {
@@ -1739,7 +1755,18 @@ async function handleSync(deps = {}) {
   }
   const body = await res.json().catch(() => ({}));
   const id = typeof body.id === "string" ? body.id : "";
-  return { id, url: `${endpoint}/${id}` };
+  const result = { id, url: `${endpoint}/${id}` };
+  if (deps.failOnFailures === true) result.gate = gateExit(await readVerdict(doFetch, `${endpoint}/${id}/summary`, token));
+  return result;
+}
+async function readVerdict(doFetch, url, token) {
+  try {
+    const res = await doFetch(url, { method: "GET", headers: { authorization: `Bearer ${token}` } });
+    const body = await res.json().catch(() => void 0);
+    return res.ok ? { statusEvent: body?.run?.statusEvent, counts: body?.counts, notRun: body?.notRun } : void 0;
+  } catch {
+    return void 0;
+  }
 }
 function reportSyncFailure(err, write) {
   if (err instanceof NotLoggedInError || err instanceof TokenRejectedError || err instanceof SyncFileError) {
@@ -1827,7 +1854,8 @@ async function defaultReadEvidence(dir) {
   if (!Array.isArray(raw)) return void 0;
   return raw.map((r) => {
     const rec = asRecord(r);
-    return { name: str(rec["name"]), passed: rec["passed"] === true };
+    const error = str(rec["error"]);
+    return { name: str(rec["name"]), passed: rec["passed"] === true, ...error !== "" ? { error } : {} };
   });
 }
 function casesFromDesign(report) {
@@ -1886,7 +1914,7 @@ async function readCairnRun(dir, deps = {}) {
     const verdicts = /* @__PURE__ */ new Map();
     for (const e of evidence ?? []) {
       if (verdicts.has(e.name)) throw new CairnEvidenceAmbiguousError(e.name);
-      verdicts.set(e.name, e.passed ? "passed" : "failed");
+      verdicts.set(e.name, e.error !== void 0 ? "blocked" : e.passed ? "passed" : "failed");
     }
     cases = casesFromApi(report, verdicts);
   } else {

package/dist/reporter-core.cjs

@@ -1100,21 +1100,26 @@ async function startRun(passed, declared) {
     },
     flush,
     async finish(reason) {
-      if (done) return;
+      if (done) return void 0;
       done = true;
       await flush();
       await offer();
+      let frozen;
       if (runId !== null && !offline) {
         const out = await client.post(`/v1/runs/${runId}/events`, {
           event: "finish",
           ...reason !== void 0 ? { reason } : {}
         });
         if (!out.ok) log(`plune: could not close run ${runId} (${out.detail || out.kind}).`);
-        else if (typeof out.body?.detached === "number" && out.body.detached > 0) {
-          log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+        else {
+          frozen = out.body?.summary ?? void 0;
+          if (typeof out.body?.detached === "number" && out.body.detached > 0) {
+            log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+          }
         }
       }
       summarise();
+      return frozen;
     },
     async leaveOpen() {
       if (done) return;

package/dist/reporter-core.d.cts

@@ -221,6 +221,17 @@ interface RunRecord {
     projectId?: string;
     schemaVersion?: number;
 }
+/**
+ * What the platform froze into a run at `finish` and answers the event with (plune#1247): the verdict a
+ * release gate is made on, never recomputed. `counts` is by the status each result is counted under — a
+ * muted case's `failed` or `broken` is under `muted`, outside both — and an absent key is zero.
+ */
+interface FrozenSummary {
+    counts: Record<string, number>;
+    /** The expected cases that never reported. */
+    notRun: string[];
+    total: number;
+}
 /** Per-element verdicts from a batch. `conflict` means two runners disagreed about one result —
  * the platform refuses to resolve that by overwriting, and neither do we. */
 interface SubmitCounts {
@@ -357,8 +368,11 @@ interface RunSession {
     add(result: PendingResult): Promise<void>;
     /** Send whatever is buffered. Safe to call when nothing is. */
     flush(): Promise<void>;
-    /** Send what is left and close the run. */
-    finish(reason?: string): Promise<void>;
+    /**
+     * Send what is left and close the run. Resolves to the summary the platform froze at `finish` (plune#1247), or
+     * `undefined` when it answered with none: no run, a refused finish, a deployment older than the summary.
+     */
+    finish(reason?: string): Promise<FrozenSummary | undefined>;
     /** Send what is left and deliberately leave the run open — the shard case (AC-03). */
     leaveOpen(): Promise<void>;
 }
@@ -592,4 +606,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-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 ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };
+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 FrozenSummary, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };

package/dist/reporter-core.d.ts

@@ -221,6 +221,17 @@ interface RunRecord {
     projectId?: string;
     schemaVersion?: number;
 }
+/**
+ * What the platform froze into a run at `finish` and answers the event with (plune#1247): the verdict a
+ * release gate is made on, never recomputed. `counts` is by the status each result is counted under — a
+ * muted case's `failed` or `broken` is under `muted`, outside both — and an absent key is zero.
+ */
+interface FrozenSummary {
+    counts: Record<string, number>;
+    /** The expected cases that never reported. */
+    notRun: string[];
+    total: number;
+}
 /** Per-element verdicts from a batch. `conflict` means two runners disagreed about one result —
  * the platform refuses to resolve that by overwriting, and neither do we. */
 interface SubmitCounts {
@@ -357,8 +368,11 @@ interface RunSession {
     add(result: PendingResult): Promise<void>;
     /** Send whatever is buffered. Safe to call when nothing is. */
     flush(): Promise<void>;
-    /** Send what is left and close the run. */
-    finish(reason?: string): Promise<void>;
+    /**
+     * Send what is left and close the run. Resolves to the summary the platform froze at `finish` (plune#1247), or
+     * `undefined` when it answered with none: no run, a refused finish, a deployment older than the summary.
+     */
+    finish(reason?: string): Promise<FrozenSummary | undefined>;
     /** Send what is left and deliberately leave the run open — the shard case (AC-03). */
     leaveOpen(): Promise<void>;
 }
@@ -592,4 +606,4 @@ interface PlatformClient {
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 
-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 ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };
+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 FrozenSummary, type KeyRef, type PendingResult, type PlatformClient, RESULT_KEY_MAX, type ReporterConfig, type ResultFile, type ResultStatus, type ResultSubmission, type RunKind, type RunMeta, type RunRecord, type RunSession, type RunStats, type RunnerLocation, type SubmitCounts, UNSUPPORTED_VARS, type UnofferedWhy, appendBatch, ciCommit, createClient, errorContextOf, failureOf, filesOf, readEnv, repoRootOf, resultKey, startRun, webLink };

package/dist/reporter-core.js

@@ -1051,21 +1051,26 @@ async function startRun(passed, declared) {
     },
     flush,
     async finish(reason) {
-      if (done) return;
+      if (done) return void 0;
       done = true;
       await flush();
       await offer();
+      let frozen;
       if (runId !== null && !offline) {
         const out = await client.post(`/v1/runs/${runId}/events`, {
           event: "finish",
           ...reason !== void 0 ? { reason } : {}
         });
         if (!out.ok) log(`plune: could not close run ${runId} (${out.detail || out.kind}).`);
-        else if (typeof out.body?.detached === "number" && out.body.detached > 0) {
-          log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+        else {
+          frozen = out.body?.summary ?? void 0;
+          if (typeof out.body?.detached === "number" && out.body.detached > 0) {
+            log(`plune: ${out.body.detached} test case(s) marked detached \u2014 this full run no longer reports them.`);
+          }
         }
       }
       summarise();
+      return frozen;
     },
     async leaveOpen() {
       if (done) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plune-ai/cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "AI-powered assertion testing for LLM apps — write assertions, run them against any provider, get a pass/fail report (local, CI, or diff).",
   "keywords": [
     "ai",