@plune-ai/cli 0.23.0 → 0.25.0

package/dist/index.cjs

@@ -1610,6 +1610,7 @@ async function handleRun(options, depsFactory) {
 }
 
 // src/cli/commands/sync.ts
+var import_node_crypto2 = require("crypto");
 var fs6 = __toESM(require("fs"), 1);
 var path5 = __toESM(require("path"), 1);
 
@@ -1794,12 +1795,18 @@ async function handleSync(deps = {}) {
   const run = readRun(cwd, deps.file);
   const doFetch = deps.fetchImpl ?? fetch;
   const endpoint = `${apiUrl}/v1/runs`;
+  const payload = JSON.stringify(run);
+  const idempotencyKey = (0, import_node_crypto2.createHash)("sha256").update(payload).digest("hex");
   let res;
   try {
     res = await doFetch(endpoint, {
       method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-      body: JSON.stringify(run)
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${token}`,
+        "idempotency-key": idempotencyKey
+      },
+      body: payload
     });
   } catch {
     throw new SyncNetworkError(apiUrl);

package/dist/index.js

@@ -1554,6 +1554,7 @@ async function handleRun(options, depsFactory) {
 }
 
 // src/cli/commands/sync.ts
+import { createHash as createHash2 } from "crypto";
 import * as fs6 from "fs";
 import * as path5 from "path";
 
@@ -1738,12 +1739,18 @@ async function handleSync(deps = {}) {
   const run = readRun(cwd, deps.file);
   const doFetch = deps.fetchImpl ?? fetch;
   const endpoint = `${apiUrl}/v1/runs`;
+  const payload = JSON.stringify(run);
+  const idempotencyKey = createHash2("sha256").update(payload).digest("hex");
   let res;
   try {
     res = await doFetch(endpoint, {
       method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-      body: JSON.stringify(run)
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${token}`,
+        "idempotency-key": idempotencyKey
+      },
+      body: payload
     });
   } catch {
     throw new SyncNetworkError(apiUrl);

package/dist/reporter-core.cjs

@@ -161,14 +161,25 @@ var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function detailOf(res) {
   try {
     const body = await res.json();
+    const q = body.quota;
     return {
+      ...typeof body.shardsExpected === "number" && Number.isInteger(body.shardsExpected) ? { shardsExpected: body.shardsExpected } : {},
       detail: typeof body.error === "string" ? body.error : "",
+      ...typeof q === "object" && q !== null && !Array.isArray(q) ? { quota: q } : {},
       ...typeof body.code === "string" && /^[a-z0-9_]{1,60}$/.test(body.code) ? { code: body.code } : {}
     };
   } catch {
     return { detail: "" };
   }
 }
+function describeQuota(q) {
+  const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+  const kind = typeof q["kind"] === "string" ? q["kind"].slice(0, 60) : "limit";
+  const [used, limit] = [num(q["used"]), num(q["limit"])];
+  const parts = [used !== void 0 && limit !== void 0 ? `${kind}: ${used} of ${limit} used` : kind];
+  if (typeof q["resetsAt"] === "string" && q["resetsAt"] !== "") parts.push(`resets ${q["resetsAt"].slice(0, 40)}`);
+  return parts.join(", ");
+}
 function classify(status) {
   if (status === 401 || status === 403) return "auth";
   if (status === 409) return "conflict";
@@ -233,12 +244,12 @@ function createClient(opts) {
       }
       const said = await detailOf(res);
       const kind = classify(res.status);
-      last = { kind, status: res.status, detail: scrub(said.detail), ...said.code !== void 0 ? { code: said.code } : {} };
+      last = { kind, status: res.status, detail: scrub(said.detail), ...said.code !== void 0 ? { code: said.code } : {}, ...said.shardsExpected !== void 0 ? { shardsExpected: said.shardsExpected } : {} };
       if (kind !== "unavailable") break;
       const said429 = parseRetryAfter(res.headers.get("retry-after"), now());
-      if (res.status === 429 && said429 === null) {
+      if (res.status === 429 && (said.quota !== void 0 || said429 === null)) {
         last.kind = "invalid";
-        last.detail = "quota exceeded (no Retry-After)";
+        last.detail = `quota exceeded (${said.quota === void 0 ? "no Retry-After" : scrub(describeQuota(said.quota))})`;
         if (said.detail) last.detail += ` \u2014 ${scrub(said.detail)}`;
         break;
       }
@@ -251,6 +262,7 @@ function createClient(opts) {
     post: (path3, body, retries) => send("POST", path3, { body: JSON.stringify(body), type: "application/json" }, retries),
     upload: (path3, bytes, contentType) => send("POST", path3, { body: bytes, type: contentType }, uploadRetries ?? DEFAULT_RETRIES),
     del: (path3) => send("DELETE", path3),
+    get: (path3) => send("GET", path3),
     async put(url, headers, source) {
       const putRetries = uploadRetries ?? 3;
       let last = { ok: false, status: null, code: "network" };
@@ -289,7 +301,18 @@ function createClient(opts) {
 // src/reporter-core/env.ts
 var path = __toESM(require("path"), 1);
 var UNSUPPORTED_VARS = ["PLUNE_GROUP"];
-var UPLOAD_CONCURRENCY = { min: 1, max: 32, default: 4 };
+var SHARDS_MAX = 1e3;
+function shardOf(env) {
+  const raw = value(env, "PLUNE_SHARD");
+  if (raw === void 0) return {};
+  const m = /^(\d{1,4})\/(\d{1,4})$/.exec(raw);
+  const [k, n] = m ? [Number(m[1]), Number(m[2])] : [0, 0];
+  if (k >= 1 && k <= n && n <= SHARDS_MAX) return { shard: { index: k, total: n } };
+  return {
+    error: `PLUNE_SHARD=${JSON.stringify(raw.slice(0, 40))} is not "k/N" with 1 <= k <= N <= ${SHARDS_MAX} (for example 2/4) - nothing was sent.`
+  };
+}
+var UPLOAD_CONCURRENCY = { min: 1, max: 32, default: 16 };
 var UPLOAD_RETRIES = { min: 0, max: 20, default: 6 };
 function value(env, name) {
   const raw = env[name]?.trim();
@@ -333,6 +356,7 @@ function readEnv(env = process.env) {
   const labels = list(env, "PLUNE_LABELS");
   const offerDiscovered = flag(env, "PLUNE_CREATE");
   const full = flag(env, "PLUNE_FULL_RUN");
+  const { shard, error: shardError } = shardOf(env);
   return {
     config: {
       ...externalKey !== void 0 ? { externalKey } : {},
@@ -353,7 +377,11 @@ function readEnv(env = process.env) {
     // Two names for two situations that end the same way. `SHARED_RUN` says other processes are
     // reporting into this run; `PROCEED` says the job will close it on its own schedule. Either
     // way this process must not be the one to call it finished.
-    keepOpen: flag(env, "PLUNE_SHARED_RUN") || flag(env, "PLUNE_PROCEED"),
+    // `PLUNE_SHARD` implies it: the run is joined by the shared key and this process does not close it
+    // by itself; `leaveOpen` reports the shard instead.
+    keepOpen: flag(env, "PLUNE_SHARED_RUN") || flag(env, "PLUNE_PROCEED") || shard !== void 0 || shardError !== void 0,
+    ...shard !== void 0 ? { shard } : {},
+    ...shardError !== void 0 ? { shardError } : {},
     ignored: UNSUPPORTED_VARS.filter((name) => value(env, name) !== void 0),
     warnings
   };
@@ -700,6 +728,7 @@ function warnIfDropped(sent, run, log) {
 }
 async function startRun(passed, declared) {
   const env = readEnv();
+  if (env.shardError !== void 0) throw new Error(env.shardError);
   const stated = Object.fromEntries(Object.entries(passed).filter(([, v]) => v !== void 0));
   const cfg = { ...env.config, ...stated };
   const log = cfg.log ?? ((line) => void process.stderr.write(`${line}
@@ -741,6 +770,9 @@ async function startRun(passed, declared) {
   const resolved = /* @__PURE__ */ new Map();
   let buffer = [];
   const discoveries = /* @__PURE__ */ new Map();
+  const held = /* @__PURE__ */ new Map();
+  let createdWithResult = 0;
+  let createdUndelivered = 0;
   let runId = null;
   let joined = false;
   let offline = token === "";
@@ -869,6 +901,7 @@ async function startRun(passed, declared) {
       specRef: result.specRef,
       rawStatus: result.rawStatus
     });
+    held.set(result.keys[0].value, result);
   }
   async function offer() {
     if (discoveries.size === 0 || offline || runId === null) return;
@@ -887,7 +920,24 @@ async function startRun(passed, declared) {
         return;
       }
       stats.offered += out.body.results.filter((r) => r?.outcome === "queued").length;
-      stats.created += out.body.results.filter((r) => r?.outcome === "created").length;
+      const made = out.body.results.filter((r) => r?.outcome === "created");
+      stats.created += made.length;
+      const submissions = [];
+      const filesByKey = /* @__PURE__ */ new Map();
+      for (const r of made) {
+        const pending = typeof r.id === "string" && r.id !== "" ? held.get(r.key?.value) : void 0;
+        if (pending === void 0) continue;
+        held.delete(r.key.value);
+        const { keys: _keys, files, ...rest } = pending;
+        submissions.push({ ...rest, testCaseId: r.id });
+        if (files !== void 0) filesByKey.set(pending.resultKey, files);
+      }
+      if (submissions.length > 0) {
+        const before = stats.deferred;
+        await send(submissions, filesByKey);
+        createdWithResult += submissions.length;
+        createdUndelivered += stats.deferred - before;
+      }
     }
   }
   function skip(kind, name, why) {
@@ -1324,6 +1374,9 @@ async function startRun(passed, declared) {
       progress();
       return;
     }
+    await send(submissions, filesByKey);
+  }
+  async function send(submissions, filesByKey) {
     for (const part of packed(submissions)) {
       if (offline) {
         defer(part);
@@ -1367,7 +1420,10 @@ async function startRun(passed, declared) {
     if (stats.rejected > 0) parts.push(`${stats.rejected} rejected`);
     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.created > 0) {
+      const recorded = createdWithResult === stats.created && createdUndelivered === 0;
+      parts.push(`${stats.created} added as cases (trusted source)${recorded ? " and their results recorded" : ""}`);
+    }
     const kinds = [stats.screenshots, stats.textFiles, stats.otherFiles];
     const sum = (what) => kinds.reduce((n, counts) => n + counts[what], 0);
     if (bucketSeen) {
@@ -1397,6 +1453,7 @@ async function startRun(passed, declared) {
       log(`::warning::${stats.deferred} result(s) were not delivered to Plune \u2014 see the reporting step's log.`);
     }
   }
+  const shardLines = [];
   return {
     get runId() {
       return runId;
@@ -1434,15 +1491,43 @@ async function startRun(passed, declared) {
       summarise();
       return frozen;
     },
-    async leaveOpen() {
-      if (done) return;
+    shardLines,
+    async leaveOpen(opts) {
+      if (done) return void 0;
       done = true;
       await flush();
       await offer();
-      if (runId !== null) {
+      let frozen;
+      const after = [];
+      const shard = env.shard;
+      let counted = false;
+      let mismatch;
+      if (runId !== null && shard !== void 0 && !offline) {
+        const out = await client.post(`/v1/runs/${runId}/events`, { event: "finish", shardIndex: shard.index, shardsExpected: shard.total });
+        if (out.ok && typeof out.body?.shardsReported === "number") {
+          counted = true;
+          frozen = out.body.summary ?? void 0;
+          const n = out.body.shardsExpected ?? shard.total;
+          if (out.body.run?.statusEvent === "finished") after.push("plune: run closed");
+          after.push(`plune: shard ${shard.index} of ${shard.total} done \u2014 ${out.body.shardsReported} of ${n} shards reported`);
+        } else if (out.ok || out.kind === "invalid") {
+          log('plune: the platform does not support shard auto-close yet \u2014 the run is left open for "plune run finish".');
+        } else if (out.code === "shards_mismatch") {
+          mismatch = new Error(
+            `PLUNE_SHARD=${shard.index}/${shard.total} says ${shard.total} shards, but run ${runId} already expects ${out.shardsExpected ?? "a different number of"} \u2014 every shard of one run must use the same N. The results are uploaded; the run is left open.`
+          );
+        } else {
+          log(`plune: could not report shard ${shard.index} of ${shard.total} to run ${runId} (${out.detail || out.kind}) \u2014 the results are uploaded; close the run with "plune run finish ${runId}".`);
+        }
+      }
+      if (runId !== null && !counted) {
         log(`plune: run ${runId} is still open \u2014 close it with "plune run finish ${runId}".`);
       }
       summarise();
+      shardLines.push(...after);
+      if (opts?.holdShardLines !== true) for (const line of after) log(line);
+      if (mismatch !== void 0) throw mismatch;
+      return frozen;
     }
   };
 }

package/dist/reporter-core.d.cts

@@ -326,7 +326,7 @@ interface ReporterConfig {
     labels?: string[];
     /** Results per request. The platform's ceiling is 500. */
     batchSize?: number;
-    /** Files in flight at once (`PLUNE_UPLOAD_CONCURRENCY`, 1 to 32, default 4). */
+    /** Files in flight at once (`PLUNE_UPLOAD_CONCURRENCY`, 1 to 32, default 16). */
     uploadConcurrency?: number;
     /** Retries of a request the platform or a bucket asked to wait for (`PLUNE_UPLOAD_RETRIES`, 0 to 20, default 6). */
     uploadRetries?: number;
@@ -377,8 +377,15 @@ interface RunSession {
      * `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>;
+    /**
+     * Send what is left and deliberately leave the run open - the shard case (AC-03). With `PLUNE_SHARD=k/N`
+     * it reports "shard k of N is done" instead (cli#110) and resolves to the summary when that was the Nth.
+     */
+    leaveOpen(opts?: {
+        holdShardLines?: boolean;
+    }): Promise<FrozenSummary | undefined>;
+    /** The closing lines of a `PLUNE_SHARD` report (`run closed`, `shard k of N done`). Printed by `leaveOpen` unless it was told to hold them for a caller that has more to say first. */
+    readonly shardLines: readonly string[];
 }
 declare function startRun(passed: ReporterConfig, declared?: readonly (readonly KeyRef[])[]): Promise<RunSession>;
 
@@ -424,11 +431,20 @@ declare function resultKey(testId: string, retry: number): string;
  * put them. `PLUNE_GROUP` stays: a run group is D6's, and a group of one run means nothing.
  */
 declare const UNSUPPORTED_VARS: readonly ["PLUNE_GROUP"];
+interface ShardOf {
+    /** 1-based. */
+    index: number;
+    total: number;
+}
 interface EnvSettings {
     /** Config fields the environment supplied. Anything passed explicitly outranks these. */
     config: Partial<ReporterConfig>;
     /** This process must not close the run — several share it, or the job closes it itself. */
     keepOpen: boolean;
+    /** `PLUNE_SHARD=k/N`: this process is shard k of N, and tells the platform when it is done (cli#110). */
+    shard?: ShardOf;
+    /** `PLUNE_SHARD` was set to something that is not `k/N`. A configuration error: the caller refuses to start. */
+    shardError?: string;
     /** Variables that were set and have nowhere to land. The caller says so once. */
     ignored: string[];
     /** Variables that were set to something unusable and fell back to their default. The caller says so once. */
@@ -562,6 +578,7 @@ type ClientOutcome<T> = {
     status: number | null;
     detail: string;
     code?: string;
+    shardsExpected?: number;
 };
 /** What a PUT to a bucket carries: a file on disk, streamed at a length known beforehand, or bytes in memory. */
 type PutSource = {
@@ -612,6 +629,8 @@ interface PlatformClient {
      * a proxy error page that echoes the request would put a token in a CI log.
      */
     del<T>(path: string): Promise<ClientOutcome<T>>;
+    /** A GET, through the same retries, classification and token scrubbing. */
+    get<T>(path: string): Promise<ClientOutcome<T>>;
     /**
      * The bytes to a short-lived link of the customer's bucket (plune-ai/plune#946): exactly the headers the
      * link came with, no token of ours. Network failures and 5xx wait and try again, up to three times; a 403

package/dist/reporter-core.d.ts

@@ -326,7 +326,7 @@ interface ReporterConfig {
     labels?: string[];
     /** Results per request. The platform's ceiling is 500. */
     batchSize?: number;
-    /** Files in flight at once (`PLUNE_UPLOAD_CONCURRENCY`, 1 to 32, default 4). */
+    /** Files in flight at once (`PLUNE_UPLOAD_CONCURRENCY`, 1 to 32, default 16). */
     uploadConcurrency?: number;
     /** Retries of a request the platform or a bucket asked to wait for (`PLUNE_UPLOAD_RETRIES`, 0 to 20, default 6). */
     uploadRetries?: number;
@@ -377,8 +377,15 @@ interface RunSession {
      * `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>;
+    /**
+     * Send what is left and deliberately leave the run open - the shard case (AC-03). With `PLUNE_SHARD=k/N`
+     * it reports "shard k of N is done" instead (cli#110) and resolves to the summary when that was the Nth.
+     */
+    leaveOpen(opts?: {
+        holdShardLines?: boolean;
+    }): Promise<FrozenSummary | undefined>;
+    /** The closing lines of a `PLUNE_SHARD` report (`run closed`, `shard k of N done`). Printed by `leaveOpen` unless it was told to hold them for a caller that has more to say first. */
+    readonly shardLines: readonly string[];
 }
 declare function startRun(passed: ReporterConfig, declared?: readonly (readonly KeyRef[])[]): Promise<RunSession>;
 
@@ -424,11 +431,20 @@ declare function resultKey(testId: string, retry: number): string;
  * put them. `PLUNE_GROUP` stays: a run group is D6's, and a group of one run means nothing.
  */
 declare const UNSUPPORTED_VARS: readonly ["PLUNE_GROUP"];
+interface ShardOf {
+    /** 1-based. */
+    index: number;
+    total: number;
+}
 interface EnvSettings {
     /** Config fields the environment supplied. Anything passed explicitly outranks these. */
     config: Partial<ReporterConfig>;
     /** This process must not close the run — several share it, or the job closes it itself. */
     keepOpen: boolean;
+    /** `PLUNE_SHARD=k/N`: this process is shard k of N, and tells the platform when it is done (cli#110). */
+    shard?: ShardOf;
+    /** `PLUNE_SHARD` was set to something that is not `k/N`. A configuration error: the caller refuses to start. */
+    shardError?: string;
     /** Variables that were set and have nowhere to land. The caller says so once. */
     ignored: string[];
     /** Variables that were set to something unusable and fell back to their default. The caller says so once. */
@@ -562,6 +578,7 @@ type ClientOutcome<T> = {
     status: number | null;
     detail: string;
     code?: string;
+    shardsExpected?: number;
 };
 /** What a PUT to a bucket carries: a file on disk, streamed at a length known beforehand, or bytes in memory. */
 type PutSource = {
@@ -612,6 +629,8 @@ interface PlatformClient {
      * a proxy error page that echoes the request would put a token in a CI log.
      */
     del<T>(path: string): Promise<ClientOutcome<T>>;
+    /** A GET, through the same retries, classification and token scrubbing. */
+    get<T>(path: string): Promise<ClientOutcome<T>>;
     /**
      * The bytes to a short-lived link of the customer's bucket (plune-ai/plune#946): exactly the headers the
      * link came with, no token of ours. Network failures and 5xx wait and try again, up to three times; a 403

package/dist/reporter-core.js

@@ -112,14 +112,25 @@ var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function detailOf(res) {
   try {
     const body = await res.json();
+    const q = body.quota;
     return {
+      ...typeof body.shardsExpected === "number" && Number.isInteger(body.shardsExpected) ? { shardsExpected: body.shardsExpected } : {},
       detail: typeof body.error === "string" ? body.error : "",
+      ...typeof q === "object" && q !== null && !Array.isArray(q) ? { quota: q } : {},
       ...typeof body.code === "string" && /^[a-z0-9_]{1,60}$/.test(body.code) ? { code: body.code } : {}
     };
   } catch {
     return { detail: "" };
   }
 }
+function describeQuota(q) {
+  const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+  const kind = typeof q["kind"] === "string" ? q["kind"].slice(0, 60) : "limit";
+  const [used, limit] = [num(q["used"]), num(q["limit"])];
+  const parts = [used !== void 0 && limit !== void 0 ? `${kind}: ${used} of ${limit} used` : kind];
+  if (typeof q["resetsAt"] === "string" && q["resetsAt"] !== "") parts.push(`resets ${q["resetsAt"].slice(0, 40)}`);
+  return parts.join(", ");
+}
 function classify(status) {
   if (status === 401 || status === 403) return "auth";
   if (status === 409) return "conflict";
@@ -184,12 +195,12 @@ function createClient(opts) {
       }
       const said = await detailOf(res);
       const kind = classify(res.status);
-      last = { kind, status: res.status, detail: scrub(said.detail), ...said.code !== void 0 ? { code: said.code } : {} };
+      last = { kind, status: res.status, detail: scrub(said.detail), ...said.code !== void 0 ? { code: said.code } : {}, ...said.shardsExpected !== void 0 ? { shardsExpected: said.shardsExpected } : {} };
       if (kind !== "unavailable") break;
       const said429 = parseRetryAfter(res.headers.get("retry-after"), now());
-      if (res.status === 429 && said429 === null) {
+      if (res.status === 429 && (said.quota !== void 0 || said429 === null)) {
         last.kind = "invalid";
-        last.detail = "quota exceeded (no Retry-After)";
+        last.detail = `quota exceeded (${said.quota === void 0 ? "no Retry-After" : scrub(describeQuota(said.quota))})`;
         if (said.detail) last.detail += ` \u2014 ${scrub(said.detail)}`;
         break;
       }
@@ -202,6 +213,7 @@ function createClient(opts) {
     post: (path3, body, retries) => send("POST", path3, { body: JSON.stringify(body), type: "application/json" }, retries),
     upload: (path3, bytes, contentType) => send("POST", path3, { body: bytes, type: contentType }, uploadRetries ?? DEFAULT_RETRIES),
     del: (path3) => send("DELETE", path3),
+    get: (path3) => send("GET", path3),
     async put(url, headers, source) {
       const putRetries = uploadRetries ?? 3;
       let last = { ok: false, status: null, code: "network" };
@@ -240,7 +252,18 @@ function createClient(opts) {
 // src/reporter-core/env.ts
 import * as path from "path";
 var UNSUPPORTED_VARS = ["PLUNE_GROUP"];
-var UPLOAD_CONCURRENCY = { min: 1, max: 32, default: 4 };
+var SHARDS_MAX = 1e3;
+function shardOf(env) {
+  const raw = value(env, "PLUNE_SHARD");
+  if (raw === void 0) return {};
+  const m = /^(\d{1,4})\/(\d{1,4})$/.exec(raw);
+  const [k, n] = m ? [Number(m[1]), Number(m[2])] : [0, 0];
+  if (k >= 1 && k <= n && n <= SHARDS_MAX) return { shard: { index: k, total: n } };
+  return {
+    error: `PLUNE_SHARD=${JSON.stringify(raw.slice(0, 40))} is not "k/N" with 1 <= k <= N <= ${SHARDS_MAX} (for example 2/4) - nothing was sent.`
+  };
+}
+var UPLOAD_CONCURRENCY = { min: 1, max: 32, default: 16 };
 var UPLOAD_RETRIES = { min: 0, max: 20, default: 6 };
 function value(env, name) {
   const raw = env[name]?.trim();
@@ -284,6 +307,7 @@ function readEnv(env = process.env) {
   const labels = list(env, "PLUNE_LABELS");
   const offerDiscovered = flag(env, "PLUNE_CREATE");
   const full = flag(env, "PLUNE_FULL_RUN");
+  const { shard, error: shardError } = shardOf(env);
   return {
     config: {
       ...externalKey !== void 0 ? { externalKey } : {},
@@ -304,7 +328,11 @@ function readEnv(env = process.env) {
     // Two names for two situations that end the same way. `SHARED_RUN` says other processes are
     // reporting into this run; `PROCEED` says the job will close it on its own schedule. Either
     // way this process must not be the one to call it finished.
-    keepOpen: flag(env, "PLUNE_SHARED_RUN") || flag(env, "PLUNE_PROCEED"),
+    // `PLUNE_SHARD` implies it: the run is joined by the shared key and this process does not close it
+    // by itself; `leaveOpen` reports the shard instead.
+    keepOpen: flag(env, "PLUNE_SHARED_RUN") || flag(env, "PLUNE_PROCEED") || shard !== void 0 || shardError !== void 0,
+    ...shard !== void 0 ? { shard } : {},
+    ...shardError !== void 0 ? { shardError } : {},
     ignored: UNSUPPORTED_VARS.filter((name) => value(env, name) !== void 0),
     warnings
   };
@@ -651,6 +679,7 @@ function warnIfDropped(sent, run, log) {
 }
 async function startRun(passed, declared) {
   const env = readEnv();
+  if (env.shardError !== void 0) throw new Error(env.shardError);
   const stated = Object.fromEntries(Object.entries(passed).filter(([, v]) => v !== void 0));
   const cfg = { ...env.config, ...stated };
   const log = cfg.log ?? ((line) => void process.stderr.write(`${line}
@@ -692,6 +721,9 @@ async function startRun(passed, declared) {
   const resolved = /* @__PURE__ */ new Map();
   let buffer = [];
   const discoveries = /* @__PURE__ */ new Map();
+  const held = /* @__PURE__ */ new Map();
+  let createdWithResult = 0;
+  let createdUndelivered = 0;
   let runId = null;
   let joined = false;
   let offline = token === "";
@@ -820,6 +852,7 @@ async function startRun(passed, declared) {
       specRef: result.specRef,
       rawStatus: result.rawStatus
     });
+    held.set(result.keys[0].value, result);
   }
   async function offer() {
     if (discoveries.size === 0 || offline || runId === null) return;
@@ -838,7 +871,24 @@ async function startRun(passed, declared) {
         return;
       }
       stats.offered += out.body.results.filter((r) => r?.outcome === "queued").length;
-      stats.created += out.body.results.filter((r) => r?.outcome === "created").length;
+      const made = out.body.results.filter((r) => r?.outcome === "created");
+      stats.created += made.length;
+      const submissions = [];
+      const filesByKey = /* @__PURE__ */ new Map();
+      for (const r of made) {
+        const pending = typeof r.id === "string" && r.id !== "" ? held.get(r.key?.value) : void 0;
+        if (pending === void 0) continue;
+        held.delete(r.key.value);
+        const { keys: _keys, files, ...rest } = pending;
+        submissions.push({ ...rest, testCaseId: r.id });
+        if (files !== void 0) filesByKey.set(pending.resultKey, files);
+      }
+      if (submissions.length > 0) {
+        const before = stats.deferred;
+        await send(submissions, filesByKey);
+        createdWithResult += submissions.length;
+        createdUndelivered += stats.deferred - before;
+      }
     }
   }
   function skip(kind, name, why) {
@@ -1275,6 +1325,9 @@ async function startRun(passed, declared) {
       progress();
       return;
     }
+    await send(submissions, filesByKey);
+  }
+  async function send(submissions, filesByKey) {
     for (const part of packed(submissions)) {
       if (offline) {
         defer(part);
@@ -1318,7 +1371,10 @@ async function startRun(passed, declared) {
     if (stats.rejected > 0) parts.push(`${stats.rejected} rejected`);
     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.created > 0) {
+      const recorded = createdWithResult === stats.created && createdUndelivered === 0;
+      parts.push(`${stats.created} added as cases (trusted source)${recorded ? " and their results recorded" : ""}`);
+    }
     const kinds = [stats.screenshots, stats.textFiles, stats.otherFiles];
     const sum = (what) => kinds.reduce((n, counts) => n + counts[what], 0);
     if (bucketSeen) {
@@ -1348,6 +1404,7 @@ async function startRun(passed, declared) {
       log(`::warning::${stats.deferred} result(s) were not delivered to Plune \u2014 see the reporting step's log.`);
     }
   }
+  const shardLines = [];
   return {
     get runId() {
       return runId;
@@ -1385,15 +1442,43 @@ async function startRun(passed, declared) {
       summarise();
       return frozen;
     },
-    async leaveOpen() {
-      if (done) return;
+    shardLines,
+    async leaveOpen(opts) {
+      if (done) return void 0;
       done = true;
       await flush();
       await offer();
-      if (runId !== null) {
+      let frozen;
+      const after = [];
+      const shard = env.shard;
+      let counted = false;
+      let mismatch;
+      if (runId !== null && shard !== void 0 && !offline) {
+        const out = await client.post(`/v1/runs/${runId}/events`, { event: "finish", shardIndex: shard.index, shardsExpected: shard.total });
+        if (out.ok && typeof out.body?.shardsReported === "number") {
+          counted = true;
+          frozen = out.body.summary ?? void 0;
+          const n = out.body.shardsExpected ?? shard.total;
+          if (out.body.run?.statusEvent === "finished") after.push("plune: run closed");
+          after.push(`plune: shard ${shard.index} of ${shard.total} done \u2014 ${out.body.shardsReported} of ${n} shards reported`);
+        } else if (out.ok || out.kind === "invalid") {
+          log('plune: the platform does not support shard auto-close yet \u2014 the run is left open for "plune run finish".');
+        } else if (out.code === "shards_mismatch") {
+          mismatch = new Error(
+            `PLUNE_SHARD=${shard.index}/${shard.total} says ${shard.total} shards, but run ${runId} already expects ${out.shardsExpected ?? "a different number of"} \u2014 every shard of one run must use the same N. The results are uploaded; the run is left open.`
+          );
+        } else {
+          log(`plune: could not report shard ${shard.index} of ${shard.total} to run ${runId} (${out.detail || out.kind}) \u2014 the results are uploaded; close the run with "plune run finish ${runId}".`);
+        }
+      }
+      if (runId !== null && !counted) {
         log(`plune: run ${runId} is still open \u2014 close it with "plune run finish ${runId}".`);
       }
       summarise();
+      shardLines.push(...after);
+      if (opts?.holdShardLines !== true) for (const line of after) log(line);
+      if (mismatch !== void 0) throw mismatch;
+      return frozen;
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plune-ai/cli",
-  "version": "0.23.0",
+  "version": "0.25.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",