@plune-ai/cli 0.5.0 → 0.7.0

package/dist/cli.cjs

@@ -41,6 +41,35 @@ var init_cjs_shims = __esm({
   }
 });
 
+// src/cli/api-url.ts
+var api_url_exports = {};
+__export(api_url_exports, {
+  FEEDBACK_URL: () => FEEDBACK_URL,
+  dashboardUrl: () => dashboardUrl,
+  resolveApiUrl: () => resolveApiUrl,
+  whereToGetAToken: () => whereToGetAToken
+});
+function resolveApiUrl(explicit) {
+  const raw = explicit ?? process.env["PLUNE_API_URL"] ?? DEFAULT_API_URL;
+  return raw.replace(/\/+$/, "");
+}
+function dashboardUrl(apiUrl = resolveApiUrl()) {
+  return apiUrl === DEFAULT_API_URL ? "https://beta.plune.ai" : void 0;
+}
+function whereToGetAToken(apiUrl = resolveApiUrl()) {
+  const web = dashboardUrl(apiUrl);
+  return web === void 0 ? `Get one from your Plune dashboard (the web app in front of ${apiUrl}), under Settings \u2192 API tokens.` : `Get one at ${web} \u2192 Settings \u2192 API tokens.`;
+}
+var FEEDBACK_URL, DEFAULT_API_URL;
+var init_api_url = __esm({
+  "src/cli/api-url.ts"() {
+    "use strict";
+    init_cjs_shims();
+    FEEDBACK_URL = "https://github.com/plune-ai/feedback/issues/new?template=feedback.yml";
+    DEFAULT_API_URL = "https://beta-api.plune.ai";
+  }
+});
+
 // src/cli/env.ts
 var env_exports = {};
 __export(env_exports, {
@@ -189,9 +218,9 @@ var init_schema = __esm({
       input_per_1k_usd: import_zod.z.number().nonnegative(),
       output_per_1k_usd: import_zod.z.number().nonnegative()
     });
-    pricingSchema = import_zod.z.record(modelPriceSchema);
+    pricingSchema = import_zod.z.record(import_zod.z.string(), modelPriceSchema);
     datasetRowSchema = import_zod.z.object({
-      vars: import_zod.z.record(import_zod.z.union([import_zod.z.string(), import_zod.z.number(), import_zod.z.boolean()])),
+      vars: import_zod.z.record(import_zod.z.string(), import_zod.z.union([import_zod.z.string(), import_zod.z.number(), import_zod.z.boolean()])),
       expected: import_zod.z.string().optional()
     });
     datasetRefSchema = import_zod.z.union([
@@ -221,7 +250,7 @@ var init_schema = __esm({
     });
     jsonSchemaAssertionSchema = import_zod.z.object({
       type: import_zod.z.literal("json-schema"),
-      schema: import_zod.z.record(import_zod.z.unknown()),
+      schema: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()),
       extract: import_zod.z.enum(["auto", "strict"]).optional()
     });
     llmJudgeAssertionSchema = import_zod.z.object({
@@ -456,7 +485,7 @@ function readHeader(headers, name) {
   return typeof v === "string" || typeof v === "number" ? v : void 0;
 }
 async function withRetry(fn, options) {
-  const { base_delay_ms = 500, sleep = defaultSleep, random = Math.random } = options;
+  const { base_delay_ms = 500, sleep: sleep2 = defaultSleep, random = Math.random } = options;
   const maxRetries = Math.max(0, Math.floor(options.max_retries));
   let attempt = 0;
   for (; ; ) {
@@ -472,7 +501,7 @@ async function withRetry(fn, options) {
       const backoff = base_delay_ms * 2 ** attempt;
       const jitter = backoff * 0.1 * random();
       const delay = Math.max(backoff + jitter, retryAfterMs(err) ?? 0);
-      await sleep(delay);
+      await sleep2(delay);
       attempt += 1;
     }
   }
@@ -808,9 +837,11 @@ var init_embedder = __esm({
         return rows.map((row) => Float32Array.from(row));
       }
       load() {
-        this.extractor ??= import("@huggingface/transformers").then(
-          ({ pipeline }) => pipeline("feature-extraction", MODEL_ID)
-        );
+        this.extractor ??= import("@huggingface/transformers").catch(() => {
+          throw new Error(
+            "The `semantic-similarity` and RAG assertions need local embeddings, which ship separately: install @huggingface/transformers to enable them. Every other assertion works without it."
+          );
+        }).then(({ pipeline }) => pipeline("feature-extraction", MODEL_ID));
         return this.extractor;
       }
     };
@@ -884,7 +915,7 @@ var init_cache = __esm({
           return void 0;
         }
       }
-      set(key, value) {
+      set(key, value2) {
         try {
           this.db.prepare(
             `INSERT INTO completions (cache_key, output, input_tokens, output_tokens, created_at)
@@ -894,7 +925,7 @@ var init_cache = __esm({
              input_tokens = excluded.input_tokens,
              output_tokens = excluded.output_tokens,
              created_at = excluded.created_at`
-          ).run(key, value.output, value.usage.input_tokens, value.usage.output_tokens, this.now());
+          ).run(key, value2.output, value2.usage.input_tokens, value2.usage.output_tokens, this.now());
         } catch {
         }
       }
@@ -932,32 +963,32 @@ var init_cache2 = __esm({
 });
 
 // src/util/canonical-json.ts
-function normalizeValue(value) {
-  if (value === null) return null;
-  if (typeof value === "boolean") return value;
-  if (typeof value === "number") {
-    if (!isFinite(value)) {
+function normalizeValue(value2) {
+  if (value2 === null) return null;
+  if (typeof value2 === "boolean") return value2;
+  if (typeof value2 === "number") {
+    if (!isFinite(value2)) {
       throw new Error(
-        `canonicalJson: non-finite number rejected: ${String(value)}`
+        `canonicalJson: non-finite number rejected: ${String(value2)}`
       );
     }
-    return value === 0 ? 0 : value;
+    return value2 === 0 ? 0 : value2;
   }
-  if (typeof value === "string") {
-    return value.normalize("NFC");
+  if (typeof value2 === "string") {
+    return value2.normalize("NFC");
   }
-  if (Array.isArray(value)) {
-    return value.map(normalizeValue);
+  if (Array.isArray(value2)) {
+    return value2.map(normalizeValue);
   }
-  if (typeof value === "object") {
-    const proto = Object.getPrototypeOf(value);
+  if (typeof value2 === "object") {
+    const proto = Object.getPrototypeOf(value2);
     if (proto !== null && proto !== Object.prototype) {
-      const name = value.constructor?.name ?? "unknown";
+      const name = value2.constructor?.name ?? "unknown";
       throw new Error(
         `canonicalJson: unsupported non-plain object (${name}) \u2014 only plain objects, arrays, and primitives are serializable`
       );
     }
-    const obj = value;
+    const obj = value2;
     const sorted = {};
     for (const key of Object.keys(obj).sort()) {
       sorted[key] = normalizeValue(obj[key]);
@@ -965,11 +996,11 @@ function normalizeValue(value) {
     return sorted;
   }
   throw new Error(
-    `canonicalJson: unsupported value type: ${typeof value}`
+    `canonicalJson: unsupported value type: ${typeof value2}`
   );
 }
-function canonicalJson(value) {
-  return JSON.stringify(normalizeValue(value));
+function canonicalJson(value2) {
+  return JSON.stringify(normalizeValue(value2));
 }
 var init_canonical_json = __esm({
   "src/util/canonical-json.ts"() {
@@ -1007,8 +1038,8 @@ function interpolate(template, ctx) {
     }
     if (key.startsWith("vars.")) {
       const name = key.slice("vars.".length);
-      const value = ctx.vars[name];
-      return value === void 0 ? match : String(value);
+      const value2 = ctx.vars[name];
+      return value2 === void 0 ? match : String(value2);
     }
     return match;
   });
@@ -1061,12 +1092,12 @@ var init_contains = __esm({
     init_interpolate();
     contains = {
       run(ctx) {
-        const value = interpolate(ctx.params.value, ctx);
+        const value2 = interpolate(ctx.params.value, ctx);
         const found = norm(ctx.output, ctx.params.ignore_case).includes(
-          norm(value, ctx.params.ignore_case)
+          norm(value2, ctx.params.ignore_case)
         );
         return Promise.resolve(
-          found ? { passed: true } : { passed: false, reason: `expected output to contain: "${value}"` }
+          found ? { passed: true } : { passed: false, reason: `expected output to contain: "${value2}"` }
         );
       }
     };
@@ -2115,6 +2146,549 @@ var init_reporters = __esm({
   }
 });
 
+// src/cli/credentials.ts
+function credentialsFile() {
+  const base = process.env["XDG_CONFIG_HOME"]?.trim() || (0, import_node_path.join)((0, import_node_os.homedir)(), ".config");
+  return (0, import_node_path.join)(base, "plune", "credentials.json");
+}
+function saveToken(token) {
+  const file = credentialsFile();
+  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(file), { recursive: true, mode: 448 });
+  (0, import_node_fs.writeFileSync)(file, JSON.stringify({ token }, null, 2) + "\n", { mode: 384 });
+  (0, import_node_fs.chmodSync)(file, 384);
+  return file;
+}
+function loadToken() {
+  try {
+    const parsed = JSON.parse((0, import_node_fs.readFileSync)(credentialsFile(), "utf-8"));
+    return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
+  } catch {
+    return null;
+  }
+}
+function clearToken() {
+  const file = credentialsFile();
+  if (!(0, import_node_fs.existsSync)(file)) return { removed: false, path: file };
+  (0, import_node_fs.rmSync)(file);
+  return { removed: true, path: file };
+}
+var import_node_fs, import_node_os, import_node_path;
+var init_credentials = __esm({
+  "src/cli/credentials.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_fs = require("fs");
+    import_node_os = require("os");
+    import_node_path = require("path");
+  }
+});
+
+// src/reporter-core/client.ts
+async function detailOf(res) {
+  try {
+    const body = await res.json();
+    return typeof body.error === "string" ? body.error : "";
+  } catch {
+    return "";
+  }
+}
+function retryAfterMs2(res) {
+  const raw = res.headers.get("retry-after");
+  if (raw === null) return null;
+  const seconds = Number(raw.trim());
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1e3 : null;
+}
+function classify3(status) {
+  if (status === 401 || status === 403) return "auth";
+  if (status === 409) return "conflict";
+  if (status === 400) return "invalid";
+  if (status === 429 || status >= 500) return "unavailable";
+  return "other";
+}
+function createClient(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const wait = opts.wait ?? sleep;
+  const base = opts.apiUrl.replace(/\/+$/, "");
+  const scrub = (text2) => opts.token === "" ? text2 : text2.split(opts.token).join("***");
+  async function post(path12, body) {
+    let last = {
+      kind: "unavailable",
+      status: null,
+      detail: "no attempt was made"
+    };
+    for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt += 1) {
+      let res;
+      try {
+        res = await doFetch(`${base}${path12}`, {
+          method: "POST",
+          headers: { "content-type": "application/json", authorization: `Bearer ${opts.token}` },
+          body: JSON.stringify(body)
+        });
+      } catch (err) {
+        last = { kind: "unavailable", status: null, detail: scrub(String(err)) };
+        if (attempt < RETRY_DELAYS_MS.length) await wait(RETRY_DELAYS_MS[attempt]);
+        continue;
+      }
+      if (res.ok) return { ok: true, status: res.status, body: await res.json() };
+      const detail = scrub(await detailOf(res));
+      const kind = classify3(res.status);
+      last = { kind, status: res.status, detail };
+      if (kind !== "unavailable") break;
+      if (attempt < RETRY_DELAYS_MS.length) {
+        await wait(retryAfterMs2(res) ?? RETRY_DELAYS_MS[attempt]);
+      }
+    }
+    return { ok: false, ...last };
+  }
+  return { post };
+}
+var RETRY_DELAYS_MS, sleep;
+var init_client = __esm({
+  "src/reporter-core/client.ts"() {
+    "use strict";
+    init_cjs_shims();
+    RETRY_DELAYS_MS = [300, 900];
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+  }
+});
+
+// src/reporter-core/env.ts
+function value(env, name) {
+  const raw = env[name]?.trim();
+  return raw === void 0 || raw === "" ? void 0 : raw;
+}
+function flag(env, name) {
+  const raw = value(env, name)?.toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+function count(env, name) {
+  const raw = value(env, name);
+  if (raw === void 0) return void 0;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : void 0;
+}
+function readEnv(env = process.env) {
+  const externalKey = value(env, "PLUNE_RUN");
+  const token = value(env, "PLUNE_TOKEN");
+  const apiUrl = value(env, "PLUNE_API_URL");
+  const fallbackPath = value(env, "PLUNE_FALLBACK");
+  const batchSize = count(env, "PLUNE_BATCH_SIZE");
+  return {
+    config: {
+      ...externalKey !== void 0 ? { externalKey } : {},
+      ...token !== void 0 ? { token } : {},
+      ...apiUrl !== void 0 ? { apiUrl } : {},
+      ...fallbackPath !== void 0 ? { fallbackPath } : {},
+      ...batchSize !== void 0 ? { batchSize } : {}
+    },
+    // 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"),
+    ignored: UNSUPPORTED_VARS.filter((name) => value(env, name) !== void 0)
+  };
+}
+var UNSUPPORTED_VARS;
+var init_env2 = __esm({
+  "src/reporter-core/env.ts"() {
+    "use strict";
+    init_cjs_shims();
+    UNSUPPORTED_VARS = [
+      "PLUNE_RUN_TITLE",
+      "PLUNE_ENV",
+      "PLUNE_LABELS",
+      "PLUNE_GROUP"
+    ];
+  }
+});
+
+// src/reporter-core/fallback.ts
+function appendBatch(file, batch) {
+  fs6.mkdirSync(path6.dirname(file), { recursive: true });
+  const line = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    runId: batch.runId,
+    externalKey: batch.externalKey,
+    results: batch.results
+  };
+  fs6.appendFileSync(file, `${JSON.stringify(line)}
+`, "utf8");
+}
+var fs6, path6, DEFAULT_FALLBACK_PATH;
+var init_fallback = __esm({
+  "src/reporter-core/fallback.ts"() {
+    "use strict";
+    init_cjs_shims();
+    fs6 = __toESM(require("fs"), 1);
+    path6 = __toESM(require("path"), 1);
+    DEFAULT_FALLBACK_PATH = path6.join(".plune", "pending-results.jsonl");
+  }
+});
+
+// src/reporter-core/session.ts
+function chunk(items, size) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+async function startRun(passed, expected) {
+  const env = readEnv();
+  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}
+`));
+  const fallbackPath = cfg.fallbackPath ?? DEFAULT_FALLBACK_PATH;
+  const externalKey = cfg.externalKey ?? null;
+  const batchSize = Math.min(cfg.batchSize ?? BATCH_DEFAULT, BATCH_MAX);
+  const token = cfg.token ?? loadToken() ?? "";
+  const client = createClient({
+    apiUrl: resolveApiUrl(cfg.apiUrl),
+    token,
+    ...cfg.fetchImpl !== void 0 ? { fetchImpl: cfg.fetchImpl } : {}
+  });
+  const stats = {
+    accepted: 0,
+    duplicate: 0,
+    conflict: 0,
+    rejected: 0,
+    unresolved: 0,
+    deferred: 0
+  };
+  const resolved = /* @__PURE__ */ new Map();
+  let buffer = [];
+  let runId = null;
+  let joined = false;
+  let offline = token === "";
+  let done = false;
+  if (offline) {
+    log('plune: no API token \u2014 run "plune login" first. Results will be written to the fallback file.');
+  }
+  if (env.ignored.length > 0) {
+    log(`plune: ignoring ${env.ignored.join(", ")} \u2014 a run has nowhere to store them yet.`);
+  }
+  function defer(results) {
+    appendBatch(fallbackPath, { runId, externalKey, results });
+    stats.deferred += results.length;
+  }
+  async function resolveKeys(values) {
+    const unknown = values.filter((k) => !resolved.has(k.value));
+    if (unknown.length === 0 || offline) return;
+    for (const part of chunk(unknown, RESOLVE_CHUNK)) {
+      const out = await client.post(
+        "/v1/test-cases/resolve",
+        { keys: part }
+      );
+      if (!out.ok) {
+        log(`plune: could not look up test cases (${out.detail || out.kind}).`);
+        return;
+      }
+      for (const row of out.body.results) resolved.set(row.key.value, row.testCaseId);
+    }
+  }
+  if (!offline) {
+    if (expected !== void 0) await resolveKeys(expected.flat());
+    const declared = expected?.slice(0, EXPECTED_MAX) ?? [];
+    const configuration = declared.length === 0 ? void 0 : {
+      expected: declared.flatMap((keys) => {
+        const hit = keys.map((k) => resolved.get(k.value)).find((v) => typeof v === "string");
+        if (typeof hit === "string") return [{ testCaseId: hit }];
+        return keys[0] === void 0 ? [] : [{ externalKey: keys[0] }];
+      })
+    };
+    if (expected !== void 0 && expected.length > EXPECTED_MAX) {
+      log(`plune: ${expected.length} tests is more than the run configuration holds \u2014 reporting the first ${EXPECTED_MAX}.`);
+    }
+    const start = await client.post("/v1/runs", {
+      schemaVersion: 2,
+      kind: cfg.kind ?? "automated",
+      ...externalKey !== null ? { externalKey } : {},
+      ...cfg.meta !== void 0 ? { meta: cfg.meta } : {},
+      ...configuration !== void 0 ? { configuration } : {}
+    });
+    if (start.ok) {
+      runId = start.body.run.id;
+      joined = start.status === 200;
+    } else {
+      log(`plune: could not start the run (${start.detail || start.kind}). Results will be written to ${fallbackPath}.`);
+    }
+  }
+  function matchFor(result) {
+    if (result.testCaseId !== void 0) return { kind: "found", testCaseId: result.testCaseId };
+    let unanswered = false;
+    for (const key of result.keys) {
+      const hit = resolved.get(key.value);
+      if (typeof hit === "string") return { kind: "found", testCaseId: hit };
+      if (hit === void 0) unanswered = true;
+    }
+    return unanswered ? { kind: "unanswered" } : { kind: "unmatched" };
+  }
+  async function flush() {
+    if (buffer.length === 0) return;
+    const pending = buffer;
+    buffer = [];
+    if (offline || runId === null) {
+      defer(pending);
+      return;
+    }
+    await resolveKeys(pending.flatMap((p) => p.keys));
+    const submissions = [];
+    const unanswered = [];
+    for (const result of pending) {
+      const match = matchFor(result);
+      if (match.kind === "found") {
+        const { keys: _keys, ...rest } = result;
+        submissions.push({ ...rest, testCaseId: match.testCaseId });
+      } else if (match.kind === "unmatched") {
+        stats.unresolved += 1;
+      } else {
+        unanswered.push(result);
+      }
+    }
+    if (unanswered.length > 0) defer(unanswered);
+    if (submissions.length === 0) 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;
+      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}).`);
+    }
+    defer(submissions);
+  }
+  function summarise() {
+    const parts = [`${stats.accepted} accepted`];
+    if (stats.duplicate > 0) parts.push(`${stats.duplicate} already reported`);
+    if (stats.conflict > 0) parts.push(`${stats.conflict} conflicting`);
+    if (stats.rejected > 0) parts.push(`${stats.rejected} rejected`);
+    if (stats.unresolved > 0) parts.push(`${stats.unresolved} with no matching test case`);
+    if (stats.deferred > 0) parts.push(`${stats.deferred} written to ${fallbackPath}`);
+    log(`plune: ${parts.join(" \xB7 ")}`);
+  }
+  return {
+    get runId() {
+      return runId;
+    },
+    get joined() {
+      return joined;
+    },
+    get stats() {
+      return stats;
+    },
+    async add(result) {
+      buffer.push(result);
+      if (buffer.length >= batchSize) await flush();
+    },
+    flush,
+    async finish(reason) {
+      if (done) return;
+      done = true;
+      await flush();
+      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}).`);
+      }
+      summarise();
+    },
+    async leaveOpen() {
+      if (done) return;
+      done = true;
+      await flush();
+      if (runId !== null) {
+        log(`plune: run ${runId} is still open \u2014 close it with "plune run finish ${runId}".`);
+      }
+      summarise();
+    }
+  };
+}
+var RESOLVE_CHUNK, BATCH_MAX, BATCH_DEFAULT, EXPECTED_MAX;
+var init_session = __esm({
+  "src/reporter-core/session.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_api_url();
+    init_credentials();
+    init_client();
+    init_env2();
+    init_fallback();
+    RESOLVE_CHUNK = 500;
+    BATCH_MAX = 500;
+    BATCH_DEFAULT = 100;
+    EXPECTED_MAX = 1e4;
+  }
+});
+
+// src/cli/commands/run-lifecycle.ts
+var run_lifecycle_exports = {};
+__export(run_lifecycle_exports, {
+  NoTokenError: () => NoTokenError,
+  RunCommandError: () => RunCommandError,
+  handleRunExec: () => handleRunExec,
+  handleRunFinish: () => handleRunFinish,
+  handleRunReport: () => handleRunReport,
+  handleRunStart: () => handleRunStart
+});
+function connect(deps) {
+  const env = readEnv();
+  const apiUrl = resolveApiUrl(deps.apiUrl ?? env.config.apiUrl);
+  const token = deps.token ?? env.config.token ?? loadToken() ?? "";
+  if (token === "") throw new NoTokenError();
+  return {
+    client: createClient({
+      apiUrl,
+      token,
+      ...deps.fetchImpl !== void 0 ? { fetchImpl: deps.fetchImpl } : {}
+    }),
+    apiUrl,
+    write: deps.write ?? ((line) => void process.stdout.write(`${line}
+`))
+  };
+}
+function runUrl(apiUrl, id) {
+  const web = dashboardUrl(apiUrl);
+  return web === void 0 ? `${apiUrl}/v1/runs/${id}` : `${web}/runs/${id}`;
+}
+async function handleRunStart(options = {}) {
+  const { client, apiUrl, write } = connect(options);
+  const env = readEnv();
+  const externalKey = options.key ?? env.config.externalKey ?? `plune-${(options.now ?? Date.now)().toString(36)}`;
+  const out = await client.post("/v1/runs", {
+    schemaVersion: 2,
+    kind: options.kind ?? "automated",
+    externalKey
+  });
+  if (!out.ok) throw new RunCommandError(`Could not start the run \u2014 ${out.detail || out.kind}.`);
+  const result = {
+    id: out.body.run.id,
+    joined: out.status === 200,
+    externalKey,
+    url: runUrl(apiUrl, out.body.run.id)
+  };
+  if (options.json === true) {
+    write(JSON.stringify(result));
+  } else {
+    write(`${result.joined ? "Joined" : "Started"} run ${result.id}`);
+    write(result.url);
+  }
+  return result;
+}
+async function handleRunFinish(id, options = {}) {
+  const { client, write } = connect(options);
+  const event = options.terminate === true ? "terminate" : "finish";
+  const out = await client.post(`/v1/runs/${id}/events`, {
+    event,
+    ...options.reason !== void 0 ? { reason: options.reason } : {}
+  });
+  if (!out.ok) {
+    throw new RunCommandError(
+      out.status === 404 ? `No run '${id}' \u2014 check the id, or whether the token belongs to the same project.` : `Could not ${event} run ${id} \u2014 ${out.detail || out.kind}.`
+    );
+  }
+  write(`Run ${id} ${event === "finish" ? "finished" : "terminated"}.`);
+}
+async function handleRunExec(options) {
+  const [command, ...args] = options.argv;
+  if (command === void 0) throw new RunCommandError("Nothing to run \u2014 pass a command after `--`.");
+  const run = await handleRunStart(options);
+  const spawnImpl = options.spawnImpl ?? import_node_child_process.spawn;
+  const code = await new Promise((resolve6) => {
+    const child = spawnImpl(command, args, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: { ...process.env, PLUNE_RUN: run.externalKey, PLUNE_PROCEED: "1" }
+    });
+    child.on("close", (exitCode) => resolve6(exitCode ?? 1));
+    child.on("error", () => resolve6(1));
+  });
+  await handleRunFinish(run.id, options);
+  return code;
+}
+async function handleRunReport(options = {}) {
+  const file = options.file ?? DEFAULT_FALLBACK_PATH;
+  const write = options.write ?? ((line) => void process.stdout.write(`${line}
+`));
+  let raw;
+  try {
+    raw = fs7.readFileSync(file, "utf8");
+  } catch {
+    throw new RunCommandError(`Nothing to send \u2014 no file at ${file}.`);
+  }
+  const lines = raw.split("\n").filter((l) => l.trim() !== "").map((l) => JSON.parse(l));
+  if (lines.length === 0) throw new RunCommandError(`Nothing to send \u2014 ${file} is empty.`);
+  const { client } = connect(options);
+  const result = { batches: lines.length, sent: 0, failed: 0 };
+  for (const line of lines) {
+    const pending = line.results.filter(isPending);
+    const ready = line.results.filter((r) => !isPending(r));
+    if (line.runId !== null && ready.length > 0) {
+      const out = await client.post(`/v1/runs/${line.runId}/results`, { results: ready });
+      if (out.ok) result.sent += ready.length;
+      else {
+        result.failed += ready.length;
+        write(`Could not send ${ready.length} result(s) to run ${line.runId} \u2014 ${out.detail || out.kind}.`);
+      }
+    }
+    if (pending.length > 0) {
+      const session = await startRun({
+        ...options.apiUrl !== void 0 ? { apiUrl: options.apiUrl } : {},
+        ...options.token !== void 0 ? { token: options.token } : {},
+        ...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {},
+        ...line.externalKey !== null ? { externalKey: line.externalKey } : {},
+        // The replay does not know whether the run is complete, so it must not say that it is.
+        log: write
+      });
+      for (const r of pending) await session.add(r);
+      await session.leaveOpen();
+      result.sent += session.stats.accepted + session.stats.duplicate;
+      result.failed += session.stats.deferred + session.stats.unresolved;
+    }
+  }
+  write(`Replayed ${result.batches} batch(es) from ${file}: ${result.sent} sent, ${result.failed} not.`);
+  return result;
+}
+var import_node_child_process, fs7, NoTokenError, RunCommandError, isPending;
+var init_run_lifecycle = __esm({
+  "src/cli/commands/run-lifecycle.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_child_process = require("child_process");
+    fs7 = __toESM(require("fs"), 1);
+    init_api_url();
+    init_credentials();
+    init_client();
+    init_env2();
+    init_fallback();
+    init_session();
+    NoTokenError = class extends Error {
+      constructor() {
+        super('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.');
+        this.name = "NoTokenError";
+      }
+    };
+    RunCommandError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "RunCommandError";
+      }
+    };
+    isPending = (r) => "keys" in r;
+  }
+});
+
 // src/cli/commands/report.ts
 var report_exports = {};
 __export(report_exports, {
@@ -2128,10 +2702,10 @@ function isRunResult(v) {
 }
 function handleReport(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const file = path6.join(cwd, ".plune", "last-run.json");
+  const file = path7.join(cwd, ".plune", "last-run.json");
   let raw;
   try {
-    raw = fs6.readFileSync(file, "utf8");
+    raw = fs8.readFileSync(file, "utf8");
   } catch {
     throw new ReportNotFoundError('No saved run found. Run "plune run" first.');
   }
@@ -2146,13 +2720,13 @@ function handleReport(opts = {}) {
   }
   return parsed;
 }
-var fs6, path6, ReportNotFoundError;
+var fs8, path7, ReportNotFoundError;
 var init_report = __esm({
   "src/cli/commands/report.ts"() {
     "use strict";
     init_cjs_shims();
-    fs6 = __toESM(require("fs"), 1);
-    path6 = __toESM(require("path"), 1);
+    fs8 = __toESM(require("fs"), 1);
+    path7 = __toESM(require("path"), 1);
     ReportNotFoundError = class extends Error {
       code = "NO_SAVED_RUN";
       constructor(message) {
@@ -2175,7 +2749,7 @@ function evalStatus(e) {
   if (statuses.includes("errored")) return "errored";
   return "passed";
 }
-function classify3(baseline, current) {
+function classify4(baseline, current) {
   if (current === "errored") return "errored";
   if (baseline === "absent") return current === "passed" ? "new-pass" : "new-fail";
   if (current === "absent") return "removed";
@@ -2189,19 +2763,19 @@ function diffRuns(baseline, current) {
   const evals = ids.map((id) => {
     const baselineP = baseMap.get(id) ?? "absent";
     const currentP = curMap.get(id) ?? "absent";
-    return { id, status: classify3(baselineP, currentP), baseline: baselineP, current: currentP };
+    return { id, status: classify4(baselineP, currentP), baseline: baselineP, current: currentP };
   });
-  const count = (s) => evals.filter((e) => e.status === s).length;
+  const count2 = (s) => evals.filter((e) => e.status === s).length;
   const summary = {
-    regressions: count("regression"),
-    improvements: count("improvement"),
-    preExistingFails: count("pre-existing-fail"),
-    newFails: count("new-fail"),
-    newPasses: count("new-pass"),
-    stablePasses: count("stable-pass"),
-    errored: count("errored"),
-    removed: count("removed"),
-    hasRegression: count("regression") > 0
+    regressions: count2("regression"),
+    improvements: count2("improvement"),
+    preExistingFails: count2("pre-existing-fail"),
+    newFails: count2("new-fail"),
+    newPasses: count2("new-pass"),
+    stablePasses: count2("stable-pass"),
+    errored: count2("errored"),
+    removed: count2("removed"),
+    hasRegression: count2("regression") > 0
   };
   return { evals, summary };
 }
@@ -2226,7 +2800,7 @@ function isRunResult2(v) {
 function loadRunResult(file, label) {
   let raw;
   try {
-    raw = fs7.readFileSync(file, "utf8");
+    raw = fs9.readFileSync(file, "utf8");
   } catch {
     throw new DiffInputError(`Cannot read ${label} run file: ${file}`);
   }
@@ -2246,12 +2820,12 @@ function handleDiff(opts) {
   const current = loadRunResult(opts.currentPath, "current");
   return diffRuns(baseline, current);
 }
-var fs7, DiffInputError;
+var fs9, DiffInputError;
 var init_diff2 = __esm({
   "src/cli/commands/diff.ts"() {
     "use strict";
     init_cjs_shims();
-    fs7 = __toESM(require("fs"), 1);
+    fs9 = __toESM(require("fs"), 1);
     init_diff();
     DiffInputError = class extends Error {
       code = "DIFF_INPUT";
@@ -2376,8 +2950,8 @@ async function runInitWizard(cwd) {
     process.exit(1);
     return;
   }
-  const outputPath = path7.join(cwd, "plune.yaml");
-  if (fs8.existsSync(outputPath)) {
+  const outputPath = path8.join(cwd, "plune.yaml");
+  if (fs10.existsSync(outputPath)) {
     const overwrite = await clack.confirm({
       message: "plune.yaml already exists. Overwrite?"
     });
@@ -2416,18 +2990,18 @@ async function runInitWizard(cwd) {
 `;
   const spin = clack.spinner();
   spin.start("Writing plune.yaml\u2026");
-  fs8.writeFileSync(outputPath, header + "\n" + (0, import_yaml2.stringify)(config), "utf8");
+  fs10.writeFileSync(outputPath, header + "\n" + (0, import_yaml2.stringify)(config), "utf8");
   spin.stop("plune.yaml created!");
-  clack.outro("Done! Run `plune run` to execute your evaluations.");
+  clack.outro("plune.yaml is ready.");
 }
-var clack, fs8, path7, import_yaml2;
+var clack, fs10, path8, import_yaml2;
 var init_wizard = __esm({
   "src/config/init/wizard.ts"() {
     "use strict";
     init_cjs_shims();
     clack = __toESM(require("@clack/prompts"), 1);
-    fs8 = __toESM(require("fs"), 1);
-    path7 = __toESM(require("path"), 1);
+    fs10 = __toESM(require("fs"), 1);
+    path8 = __toESM(require("path"), 1);
     import_yaml2 = require("yaml");
     init_errors();
   }
@@ -2435,21 +3009,21 @@ var init_wizard = __esm({
 
 // src/cli/templates/index.ts
 function writeTemplateFile(cwd, rel, content, force) {
-  const target = path8.join(cwd, rel);
-  if (!force && fs9.existsSync(target)) {
+  const target = path9.join(cwd, rel);
+  if (!force && fs11.existsSync(target)) {
     return "skipped";
   }
-  fs9.mkdirSync(path8.dirname(target), { recursive: true });
-  fs9.writeFileSync(target, content, "utf8");
+  fs11.mkdirSync(path9.dirname(target), { recursive: true });
+  fs11.writeFileSync(target, content, "utf8");
   return "written";
 }
-var fs9, path8, ENV_EXAMPLE_TPL, EXAMPLE_JSONL_TPL, PLUNE_YAML_TPL;
+var fs11, path9, ENV_EXAMPLE_TPL, EXAMPLE_JSONL_TPL, PLUNE_YAML_TPL;
 var init_templates = __esm({
   "src/cli/templates/index.ts"() {
     "use strict";
     init_cjs_shims();
-    fs9 = __toESM(require("fs"), 1);
-    path8 = __toESM(require("path"), 1);
+    fs11 = __toESM(require("fs"), 1);
+    path9 = __toESM(require("path"), 1);
     ENV_EXAMPLE_TPL = `# Copy this file to .env and replace the placeholders with your real keys.
 # .env is gitignored; .env.example is safe to commit.
 # Plune reads whichever key matches your configured provider.
@@ -2485,6 +3059,7 @@ evals:
 // src/cli/commands/init.ts
 var init_exports = {};
 __export(init_exports, {
+  NEXT_STEPS: () => NEXT_STEPS,
   initCommand: () => initCommand
 });
 function reportWrite(cwd, rel, content, force) {
@@ -2504,8 +3079,9 @@ async function initCommand({ cwd, force, yes = false }) {
   for (const [rel, content] of TEMPLATES) {
     reportWrite(cwd, rel, content, force);
   }
+  process.stdout.write(NEXT_STEPS);
 }
-var TEMPLATES;
+var TEMPLATES, NEXT_STEPS;
 var init_init = __esm({
   "src/cli/commands/init.ts"() {
     "use strict";
@@ -2516,43 +3092,14 @@ var init_init = __esm({
       ["datasets/example.jsonl", EXAMPLE_JSONL_TPL],
       [".env.example", ENV_EXAMPLE_TPL]
     ];
-  }
-});
-
-// src/cli/credentials.ts
-function credentialsFile() {
-  const base = process.env["XDG_CONFIG_HOME"]?.trim() || (0, import_node_path.join)((0, import_node_os.homedir)(), ".config");
-  return (0, import_node_path.join)(base, "plune", "credentials.json");
-}
-function saveToken(token) {
-  const file = credentialsFile();
-  (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(file), { recursive: true, mode: 448 });
-  (0, import_node_fs.writeFileSync)(file, JSON.stringify({ token }, null, 2) + "\n", { mode: 384 });
-  (0, import_node_fs.chmodSync)(file, 384);
-  return file;
-}
-function loadToken() {
-  try {
-    const parsed = JSON.parse((0, import_node_fs.readFileSync)(credentialsFile(), "utf-8"));
-    return typeof parsed.token === "string" && parsed.token.length > 0 ? parsed.token : null;
-  } catch {
-    return null;
-  }
-}
-function clearToken() {
-  const file = credentialsFile();
-  if (!(0, import_node_fs.existsSync)(file)) return { removed: false, path: file };
-  (0, import_node_fs.rmSync)(file);
-  return { removed: true, path: file };
-}
-var import_node_fs, import_node_os, import_node_path;
-var init_credentials = __esm({
-  "src/cli/credentials.ts"() {
-    "use strict";
-    init_cjs_shims();
-    import_node_fs = require("fs");
-    import_node_os = require("os");
-    import_node_path = require("path");
+    NEXT_STEPS = [
+      "",
+      "Next:",
+      "  1. plune run     \u2014 runs locally. No account, no token needed.",
+      "  2. plune login   \u2014 only if you want history and trends: paste a token from the dashboard.",
+      "  3. plune sync    \u2014 sends the last run to the platform.",
+      ""
+    ].join("\n");
   }
 });
 
@@ -2560,25 +3107,81 @@ var init_credentials = __esm({
 var login_exports = {};
 __export(login_exports, {
   EmptyTokenError: () => EmptyTokenError,
-  handleLogin: () => handleLogin
+  LoginHttpError: () => LoginHttpError,
+  LoginNetworkError: () => LoginNetworkError,
+  TokenRejectedError: () => TokenRejectedError,
+  handleLogin: () => handleLogin,
+  reportLoginFailure: () => reportLoginFailure
 });
-function handleLogin(opts) {
-  const token = opts.token.trim();
-  if (token.length === 0) throw new EmptyTokenError();
-  return { path: saveToken(token) };
+async function handleLogin(deps) {
+  const token = deps.token.trim();
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  if (token.length === 0) throw new EmptyTokenError(apiUrl);
+  if (deps.skipVerify === true) return { path: saveToken(token), verified: false };
+  const doFetch = deps.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await doFetch(`${apiUrl}/v1/runs?limit=1`, {
+      headers: { authorization: `Bearer ${token}` }
+    });
+  } catch {
+    throw new LoginNetworkError(apiUrl);
+  }
+  await res.text().catch(() => "");
+  if (res.status === 401) throw new TokenRejectedError(apiUrl);
+  if (!res.ok) throw new LoginHttpError(res.status);
+  return { path: saveToken(token), verified: true };
+}
+function reportLoginFailure(err, write) {
+  if (err instanceof EmptyTokenError || err instanceof TokenRejectedError) {
+    write(`${err.message}
+`);
+    return 2;
+  }
+  if (err instanceof LoginNetworkError || err instanceof LoginHttpError) {
+    write(`${err.message}
+`);
+    return 1;
+  }
+  return null;
 }
-var EmptyTokenError;
+var EmptyTokenError, TokenRejectedError, LoginNetworkError, LoginHttpError;
 var init_login = __esm({
   "src/cli/commands/login.ts"() {
     "use strict";
     init_cjs_shims();
+    init_api_url();
     init_credentials();
     EmptyTokenError = class extends Error {
-      constructor() {
-        super("No API token provided. Pass --token <token> or pipe it via stdin.");
+      constructor(apiUrl = resolveApiUrl()) {
+        super(
+          `No API token provided. ${whereToGetAToken(apiUrl)} Then pass --token <token> or pipe it via stdin.`
+        );
         this.name = "EmptyTokenError";
       }
     };
+    TokenRejectedError = class extends Error {
+      constructor(apiUrl = resolveApiUrl()) {
+        super(`That API token was rejected (401). Nothing was saved. ${whereToGetAToken(apiUrl)}`);
+        this.name = "TokenRejectedError";
+      }
+    };
+    LoginNetworkError = class extends Error {
+      constructor(apiUrl) {
+        super(
+          `Could not reach the Plune API at ${apiUrl}, so the token was not checked and NOT saved. Try again, or use --skip-verify to save it without checking.`
+        );
+        this.name = "LoginNetworkError";
+      }
+    };
+    LoginHttpError = class extends Error {
+      constructor(status) {
+        super(
+          `The Plune API returned ${status} while checking the token, so it was NOT saved. Try again.`
+        );
+        this.name = "LoginHttpError";
+      }
+    };
   }
 });
 
@@ -2599,8 +3202,8 @@ var init_logout = __esm({
 });
 
 // src/types/run-result-schema.ts
-function parseRunResult(value) {
-  return runResultSchema.parse(value);
+function parseRunResult(value2) {
+  return runResultSchema.parse(value2);
 }
 var import_zod2, RUN_RESULT_SCHEMA_VERSION, binaryVerdictSchema, assertionResultRecordSchema, usageSchema, runErrorSchema, rowResultSchema, summarySchema, evalResultSchema, runResultSchema;
 var init_run_result_schema = __esm({
@@ -2630,7 +3233,7 @@ var init_run_result_schema = __esm({
       message: import_zod2.z.string()
     });
     rowResultSchema = import_zod2.z.object({
-      vars: import_zod2.z.record(import_zod2.z.unknown()),
+      vars: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()),
       output: import_zod2.z.string().nullable(),
       cached: import_zod2.z.boolean(),
       usage: usageSchema.optional(),
@@ -2671,19 +3274,15 @@ __export(sync_exports, {
   SyncFileError: () => SyncFileError,
   SyncHttpError: () => SyncHttpError,
   SyncNetworkError: () => SyncNetworkError,
-  TokenRejectedError: () => TokenRejectedError,
+  TokenRejectedError: () => TokenRejectedError2,
   handleSync: () => handleSync,
   reportSyncFailure: () => reportSyncFailure
 });
-function resolveApiUrl(explicit) {
-  const raw = explicit ?? process.env["PLUNE_API_URL"] ?? DEFAULT_API_URL;
-  return raw.replace(/\/+$/, "");
-}
 function readRun(cwd, file) {
-  const target = file !== void 0 ? path9.resolve(cwd, file) : path9.join(cwd, ".plune", "last-run.json");
+  const target = file !== void 0 ? path10.resolve(cwd, file) : path10.join(cwd, ".plune", "last-run.json");
   let raw;
   try {
-    raw = fs10.readFileSync(target, "utf8");
+    raw = fs12.readFileSync(target, "utf8");
   } catch {
     throw new SyncFileError(
       file !== void 0 ? `Run file not found: ${target}` : 'No run to sync. Run "plune run" first (or pass --file <path>).'
@@ -2729,7 +3328,7 @@ async function handleSync(deps = {}) {
   }
   if (!res.ok) {
     const detail = await safeErrorDetail(res);
-    if (res.status === 401) throw new TokenRejectedError();
+    if (res.status === 401) throw new TokenRejectedError2();
     throw new SyncHttpError(res.status, detail);
   }
   const body = await res.json().catch(() => ({}));
@@ -2737,7 +3336,7 @@ async function handleSync(deps = {}) {
   return { id, url: `${endpoint}/${id}` };
 }
 function reportSyncFailure(err, write) {
-  if (err instanceof NotLoggedInError || err instanceof TokenRejectedError || err instanceof SyncFileError) {
+  if (err instanceof NotLoggedInError || err instanceof TokenRejectedError2 || err instanceof SyncFileError) {
     write(err.message + "\n");
     return 2;
   }
@@ -2747,23 +3346,23 @@ function reportSyncFailure(err, write) {
   }
   return null;
 }
-var fs10, path9, DEFAULT_API_URL, NotLoggedInError, TokenRejectedError, SyncFileError, SyncNetworkError, SyncHttpError;
+var fs12, path10, NotLoggedInError, TokenRejectedError2, SyncFileError, SyncNetworkError, SyncHttpError;
 var init_sync = __esm({
   "src/cli/commands/sync.ts"() {
     "use strict";
     init_cjs_shims();
-    fs10 = __toESM(require("fs"), 1);
-    path9 = __toESM(require("path"), 1);
+    fs12 = __toESM(require("fs"), 1);
+    path10 = __toESM(require("path"), 1);
     init_run_result_schema();
+    init_api_url();
     init_credentials();
-    DEFAULT_API_URL = "https://beta-api.plune.ai";
     NotLoggedInError = class extends Error {
       constructor() {
         super('Not logged in. Run "plune login" first to save your API token.');
         this.name = "NotLoggedInError";
       }
     };
-    TokenRejectedError = class extends Error {
+    TokenRejectedError2 = class extends Error {
       constructor() {
         super(
           'Your API token was rejected (revoked or invalid). Run "plune login" with a fresh token.'
@@ -2796,6 +3395,273 @@ var init_sync = __esm({
   }
 });
 
+// src/cli/commands/cairn-artifact.ts
+async function findLatestCairnRun(runsDir = "runs") {
+  const entries = await fs13.readdir(runsDir, { withFileTypes: true }).catch(() => null);
+  if (entries === null) throw new NoCairnRunsError(runsDir);
+  let newest;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path11.join(runsDir, entry.name);
+    try {
+      const report = await fs13.lstat(path11.join(dir, "report.json"));
+      if (!report.isFile()) continue;
+      if (newest === void 0 || report.mtimeMs > newest.at) {
+        newest = { dir, at: report.mtimeMs };
+      }
+    } catch {
+    }
+  }
+  if (newest === void 0) throw new NoCairnRunsError(runsDir);
+  return newest.dir;
+}
+async function readJson(file) {
+  try {
+    return JSON.parse(await fs13.readFile(file, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function defaultReadEvidence(dir) {
+  const raw = await readJson(path11.join(dir, "api-evidence.json"));
+  if (!Array.isArray(raw)) return void 0;
+  return raw.map((r) => {
+    const rec = asRecord(r);
+    return { name: str(rec["name"]), passed: rec["passed"] === true };
+  });
+}
+function casesFromDesign(report) {
+  const list = Array.isArray(report["testCases"]) ? report["testCases"] : [];
+  return list.map((raw) => {
+    const c = asRecord(raw);
+    const steps = (Array.isArray(c["steps"]) ? c["steps"] : []).map((s) => str(s)).filter((s) => s !== "");
+    return {
+      stableId: str(c["stableId"]),
+      title: str(c["title"], "untitled case"),
+      execution: c["execution"] === "manual" ? "manual" : "auto",
+      steps: steps.length > 0 ? steps : ["(no steps recorded)"],
+      expected: str(c["expected"], "(no expected result recorded)"),
+      ...typeof c["technique"] === "string" ? { technique: c["technique"] } : {},
+      ...typeof c["priority"] === "string" ? { priority: c["priority"] } : {}
+    };
+  });
+}
+function casesFromApi(report, verdicts) {
+  const list = Array.isArray(report["cases"]) ? report["cases"] : [];
+  return list.map((raw) => {
+    const c = asRecord(raw);
+    const name = str(c["name"], "unnamed operation");
+    const request = `${str(c["method"], "GET")} ${str(c["path"], "/")}`;
+    const verdict = verdicts.get(name);
+    return {
+      stableId: str(c["stableId"]),
+      title: name,
+      execution: "auto",
+      steps: [request],
+      expected: `HTTP ${str(c["expectedStatus"], "default")}`,
+      ...verdict !== void 0 ? { verdict } : {},
+      ...typeof c["technique"] === "string" ? { technique: c["technique"] } : {}
+    };
+  });
+}
+async function readCairnRun(dir, deps = {}) {
+  const raw = await readJson(path11.join(dir, "report.json"));
+  if (raw === void 0) throw new CairnRunNotFoundError(dir);
+  const report = asRecord(raw);
+  if (report["schemaVersion"] !== SUPPORTED_ARTIFACT_VERSION) {
+    throw new CairnRunVersionError(report["schemaVersion"]);
+  }
+  if (report["partial"] === true) {
+    throw new CairnRunPartialError(str(report["error"], "no reason recorded"));
+  }
+  const mode = report["mode"];
+  if (mode !== "design" && mode !== "explore" && mode !== "api") {
+    throw new CairnRunVersionError(
+      `${SUPPORTED_ARTIFACT_VERSION} (unknown run mode ${String(mode)})`
+    );
+  }
+  let cases;
+  if (mode === "api") {
+    const evidence = await (deps.readEvidence ?? defaultReadEvidence)(dir);
+    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");
+    }
+    cases = casesFromApi(report, verdicts);
+  } else {
+    cases = casesFromDesign(report);
+  }
+  return {
+    schemaVersion: INGEST_SCHEMA_VERSION,
+    run: {
+      runId: str(report["runId"], path11.basename(dir)),
+      mode,
+      target: str(report["url"], "unknown")
+    },
+    cases
+  };
+}
+var fs13, path11, SUPPORTED_ARTIFACT_VERSION, INGEST_SCHEMA_VERSION, NoCairnRunsError, CairnRunNotFoundError, CairnRunVersionError, CairnRunPartialError, CairnEvidenceAmbiguousError, asRecord, str;
+var init_cairn_artifact = __esm({
+  "src/cli/commands/cairn-artifact.ts"() {
+    "use strict";
+    init_cjs_shims();
+    fs13 = __toESM(require("fs/promises"), 1);
+    path11 = __toESM(require("path"), 1);
+    SUPPORTED_ARTIFACT_VERSION = 1;
+    INGEST_SCHEMA_VERSION = 1;
+    NoCairnRunsError = class extends Error {
+      constructor(runsDir) {
+        super(`No Cairn run found under ${runsDir} \u2014 name the directory instead: plune ingest <dir>.`);
+        this.name = "NoCairnRunsError";
+      }
+    };
+    CairnRunNotFoundError = class extends Error {
+      constructor(dir) {
+        super(
+          `No Cairn run found in ${dir} \u2014 expected a report.json written by "cairn design|explore|api".`
+        );
+        this.name = "CairnRunNotFoundError";
+      }
+    };
+    CairnRunVersionError = class extends Error {
+      constructor(found) {
+        super(
+          found === void 0 ? "This run predates versioned Cairn artifacts. Re-run it with Cairn 0.7.0 or newer, which stamps the format so it can be read safely." : `Unsupported Cairn artifact version ${String(found)} (this CLI reads version ${SUPPORTED_ARTIFACT_VERSION}). Upgrade @plune-ai/cli.`
+        );
+        this.name = "CairnRunVersionError";
+      }
+    };
+    CairnRunPartialError = class extends Error {
+      constructor(reason) {
+        super(`That Cairn run did not finish, so its cases are incomplete: ${reason}`);
+        this.name = "CairnRunPartialError";
+      }
+    };
+    CairnEvidenceAmbiguousError = class extends Error {
+      constructor(name) {
+        super(
+          `Cannot attach results safely: the operation "${name}" appears more than once in this run's evidence, and the evidence file carries no case identity to disambiguate it. Nothing was uploaded.`
+        );
+        this.name = "CairnEvidenceAmbiguousError";
+      }
+    };
+    asRecord = (v) => typeof v === "object" && v !== null ? v : {};
+    str = (v, fallback = "") => typeof v === "string" && v !== "" ? v : fallback;
+  }
+});
+
+// src/cli/commands/ingest.ts
+var ingest_exports = {};
+__export(ingest_exports, {
+  IngestHttpError: () => IngestHttpError,
+  IngestNetworkError: () => IngestNetworkError,
+  IngestNotLoggedInError: () => IngestNotLoggedInError,
+  IngestTokenRejectedError: () => IngestTokenRejectedError,
+  formatIngestResult: () => formatIngestResult,
+  handleIngest: () => handleIngest,
+  reportIngestFailure: () => reportIngestFailure
+});
+async function safeErrorDetail2(res) {
+  try {
+    const body = await res.json();
+    return typeof body.error === "string" ? body.error : "";
+  } catch {
+    return "";
+  }
+}
+async function handleIngest(deps) {
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  const token = (deps.loadToken ?? loadToken)();
+  if (token === null) throw new IngestNotLoggedInError();
+  const dir = deps.dir ?? await findLatestCairnRun(deps.runsDir);
+  const payload = await readCairnRun(dir);
+  const doFetch = deps.fetchImpl ?? fetch;
+  const endpoint = `${apiUrl}/v1/ingest/cairn`;
+  let res;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify(payload)
+    });
+  } catch {
+    throw new IngestNetworkError(apiUrl);
+  }
+  if (!res.ok) {
+    const detail = await safeErrorDetail2(res);
+    if (res.status === 401) throw new IngestTokenRejectedError();
+    throw new IngestHttpError(res.status, detail);
+  }
+  const body = await res.json().catch(() => ({}));
+  return {
+    runId: typeof body.runId === "string" ? body.runId : "",
+    linked: typeof body.linked === "number" ? body.linked : 0,
+    proposed: typeof body.proposed === "number" ? body.proposed : 0,
+    skipped: typeof body.skipped === "number" ? body.skipped : 0
+  };
+}
+function reportIngestFailure(err, write) {
+  if (err instanceof IngestNotLoggedInError || err instanceof IngestTokenRejectedError || err instanceof CairnRunNotFoundError || err instanceof NoCairnRunsError || err instanceof CairnRunVersionError || err instanceof CairnRunPartialError || err instanceof CairnEvidenceAmbiguousError) {
+    write(`${err.message}
+`);
+    return 2;
+  }
+  if (err instanceof IngestNetworkError || err instanceof IngestHttpError) {
+    write(`${err.message}
+`);
+    return 1;
+  }
+  return null;
+}
+function formatIngestResult(r) {
+  const lines = [
+    `Ingested Cairn run \u2192 ${r.runId}`,
+    `  ${r.linked} result(s) attached to existing cases`,
+    `  ${r.proposed} case(s) proposed \u2014 review them in Plune to accept`,
+    `  ${r.skipped} skipped (already queued, already rejected, repeated, or never executed)`
+  ];
+  return `${lines.join("\n")}
+`;
+}
+var IngestNotLoggedInError, IngestTokenRejectedError, IngestNetworkError, IngestHttpError;
+var init_ingest = __esm({
+  "src/cli/commands/ingest.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_api_url();
+    init_credentials();
+    init_cairn_artifact();
+    IngestNotLoggedInError = class extends Error {
+      constructor() {
+        super('Not logged in. Run "plune login" first to save your API token.');
+        this.name = "IngestNotLoggedInError";
+      }
+    };
+    IngestTokenRejectedError = class extends Error {
+      constructor() {
+        super('Your API token was rejected (401). Run "plune login" again with a fresh token.');
+        this.name = "IngestTokenRejectedError";
+      }
+    };
+    IngestNetworkError = class extends Error {
+      constructor(apiUrl) {
+        super(`Could not reach the Plune API at ${apiUrl}. Check your connection, then try again.`);
+        this.name = "IngestNetworkError";
+      }
+    };
+    IngestHttpError = class extends Error {
+      constructor(status, detail) {
+        super(`Plune API returned ${status}${detail !== "" ? ` \u2014 ${detail}` : ""}.`);
+        this.status = status;
+        this.name = "IngestHttpError";
+      }
+      status;
+    };
+  }
+});
+
 // src/cli.ts
 var cli_exports = {};
 __export(cli_exports, {
@@ -2803,6 +3669,7 @@ __export(cli_exports, {
 });
 module.exports = __toCommonJS(cli_exports);
 init_cjs_shims();
+init_api_url();
 var import_commander = require("commander");
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
@@ -2833,10 +3700,17 @@ function failUnexpected(err, verbose) {
   } else {
     process.stderr.write(String(err) + "\n");
   }
+  process.stderr.write(
+    `This one is on us. Run again with --verbose and send the output: ${FEEDBACK_URL}
+`
+  );
   process.exit(1);
 }
 async function readTokenFromStdin() {
   if (process.stdin.isTTY === true) {
+    const { resolveApiUrl: resolveApiUrl2, whereToGetAToken: whereToGetAToken2 } = await Promise.resolve().then(() => (init_api_url(), api_url_exports));
+    process.stderr.write(`${whereToGetAToken2(resolveApiUrl2())}
+`);
     process.stderr.write("Paste your API token, then press Enter:\n");
   }
   const { createInterface } = await import("readline");
@@ -2852,7 +3726,7 @@ function createProgram() {
   const program = new import_commander.Command();
   program.name("plune").description("Plune \u2014 AI-powered assertion testing CLI").version(pkg.version);
   program.option("-c, --config <path>", "Path to plune.yaml config file (applies to all commands)").option("-v, --verbose", "Verbose output, including stack traces on unexpected errors", false).option("--no-color", "Disable colored output regardless of TTY");
-  program.command("run").description("Run assertions against a dataset").option("--dry-run", "Estimate cost/tokens; do not call the model", false).option("--config <path>", "Path to plune.yaml config file").option(
+  const runCommand = program.command("run").description("Run assertions against a dataset").option("--dry-run", "Estimate cost/tokens; do not call the model", false).option("--config <path>", "Path to plune.yaml config file").option(
     "--only <selector>",
     "Run a subset by eval id or tag (repeatable)",
     (val, prev) => [...prev, val],
@@ -2928,6 +3802,58 @@ function createProgram() {
       }
     }
   );
+  const failRunCommand = async (err, verbose) => {
+    const { NoTokenError: NoTokenError2, RunCommandError: RunCommandError2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
+    if (err instanceof NoTokenError2) {
+      process.stderr.write(err.message + "\n");
+      process.exit(2);
+    }
+    if (err instanceof RunCommandError2) {
+      process.stderr.write(err.message + "\n");
+      process.exit(1);
+    }
+    failUnexpected(err, verbose);
+    process.exit(1);
+  };
+  const verboseOf = (command) => command.optsWithGlobals().verbose === true;
+  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));
+      await handleRunStart2({ ...options.key !== void 0 ? { key: options.key } : {}, json: options.json });
+    } catch (err) {
+      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(async (id, options, command) => {
+    try {
+      const { handleRunFinish: handleRunFinish2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
+      await handleRunFinish2(id, {
+        terminate: options.terminate,
+        ...options.reason !== void 0 ? { reason: options.reason } : {}
+      });
+    } catch (err) {
+      await failRunCommand(err, verboseOf(command));
+    }
+  });
+  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) => {
+    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 } : {}
+      });
+    } catch (err) {
+      await failRunCommand(err, verboseOf(command));
+    }
+  });
+  runCommand.command("report").description("Send what the reporter could not \u2014 replays .plune/pending-results.jsonl").option("--file <path>", "The fallback file to replay").action(async (options, command) => {
+    try {
+      const { handleRunReport: handleRunReport2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
+      await handleRunReport2({ ...options.file !== void 0 ? { file: options.file } : {} });
+    } catch (err) {
+      await failRunCommand(err, verboseOf(command));
+    }
+  });
   program.command("report").description("Render the most recent run in a chosen format").option("--format <fmt>", "console | json | markdown", "console").option("-o, --output <path>", "Write the report to a file instead of stdout").action(async (options, command) => {
     const globals = command.optsWithGlobals();
     const [{ loadEnv: loadEnv2 }, { handleReport: handleReport2, ReportNotFoundError: ReportNotFoundError2 }, { renderReport: renderReport2 }] = await Promise.all([
@@ -2991,18 +3917,26 @@ function createProgram() {
       failUnexpected(err, verbose);
     }
   });
-  program.command("login").description("Save your Plune API token so the CLI can reach the platform").option("--token <token>", "API token (omit to paste it / pipe it via stdin)").action(async (options, command) => {
+  program.command("login").description("Save your Plune API token (get one in the dashboard: Settings \u2192 API tokens)").option("--token <token>", "API token (omit to paste it / pipe it via stdin)").option(
+    "--skip-verify",
+    "Save without checking the token against the API (offline setup)",
+    false
+  ).action(async (options, command) => {
     const verbose = command.optsWithGlobals().verbose === true;
-    const { handleLogin: handleLogin2, EmptyTokenError: EmptyTokenError2 } = await Promise.resolve().then(() => (init_login(), login_exports));
+    const { handleLogin: handleLogin2, reportLoginFailure: reportLoginFailure2 } = await Promise.resolve().then(() => (init_login(), login_exports));
     try {
       const token = options.token ?? await readTokenFromStdin();
-      const { path: path10 } = handleLogin2({ token });
-      process.stdout.write(`Logged in. Token saved to ${path10}
-`);
+      const { path: path12, verified } = await handleLogin2({ token, skipVerify: options.skipVerify });
+      process.stdout.write(
+        verified ? `Logged in. Token checked against the API and saved to ${path12}
+` : `Token saved to ${path12} WITHOUT being checked (--skip-verify).
+`
+      );
     } catch (err) {
-      if (err instanceof EmptyTokenError2) {
-        process.stderr.write(err.message + "\n");
-        process.exit(2);
+      const code = reportLoginFailure2(err, (s) => process.stderr.write(s));
+      if (code !== null) {
+        maybeStack(err, verbose);
+        process.exitCode = code;
         return;
       }
       failUnexpected(err, verbose);
@@ -3012,9 +3946,9 @@ function createProgram() {
     const verbose = command.optsWithGlobals().verbose === true;
     const { handleLogout: handleLogout2 } = await Promise.resolve().then(() => (init_logout(), logout_exports));
     try {
-      const { removed, path: path10 } = handleLogout2();
+      const { removed, path: path12 } = handleLogout2();
       process.stdout.write(
-        removed ? `Logged out. Removed ${path10}
+        removed ? `Logged out. Removed ${path12}
 ` : "Not logged in \u2014 nothing to remove.\n"
       );
     } catch (err) {
@@ -3043,6 +3977,24 @@ function createProgram() {
       failUnexpected(err, verbose);
     }
   });
+  program.command("ingest").argument("[dir]", "A Cairn run directory; omit it for the newest run under ./runs").description("Record a Cairn run in Plune \u2014 generated cases arrive as review proposals").action(async (dir, _options, command) => {
+    const globals = command.optsWithGlobals();
+    const verbose = globals.verbose === true;
+    const { handleIngest: handleIngest2, reportIngestFailure: reportIngestFailure2, formatIngestResult: formatIngestResult2 } = await Promise.resolve().then(() => (init_ingest(), ingest_exports));
+    try {
+      process.stdout.write(
+        formatIngestResult2(await handleIngest2({ ...dir !== void 0 ? { dir } : {} }))
+      );
+    } catch (err) {
+      const code = reportIngestFailure2(err, (s) => process.stderr.write(s));
+      if (code !== null) {
+        maybeStack(err, verbose);
+        process.exitCode = code;
+        return;
+      }
+      failUnexpected(err, verbose);
+    }
+  });
   program.on("command:*", (operands) => {
     process.stderr.write(`Unknown command: ${operands.join(" ")}
 `);