@plune-ai/cli 0.27.0 → 0.29.0

package/dist/cli.cjs

@@ -555,22 +555,22 @@ var init_prices = __esm({
 });
 
 // src/providers/cost.ts
-function priceFrom(price, usage2) {
-  return usage2.input_tokens / 1e3 * price.input_per_1k_usd + usage2.output_tokens / 1e3 * price.output_per_1k_usd;
+function priceFrom(price, usage3) {
+  return usage3.input_tokens / 1e3 * price.input_per_1k_usd + usage3.output_tokens / 1e3 * price.output_per_1k_usd;
 }
-function resolveCost(usage2, model, reportedCostUsd, overrides, deps = {}) {
+function resolveCost(usage3, model, reportedCostUsd, overrides, deps = {}) {
   const table = deps.table ?? PRICE_TABLE;
   const warn = deps.warn ?? defaultWarn;
   const override = overrides?.[model];
   if (override !== void 0) {
-    return priceFrom(override, usage2);
+    return priceFrom(override, usage3);
   }
   if (reportedCostUsd !== void 0) {
     return reportedCostUsd;
   }
   const tablePrice = table[model];
   if (tablePrice !== void 0) {
-    return priceFrom(tablePrice, usage2);
+    return priceFrom(tablePrice, usage3);
   }
   warn(
     `plune: no price for model "${model}" \u2014 reporting cost_usd=0. Set pricing["${model}"] in plune.yaml to track its cost.`
@@ -622,14 +622,15 @@ function makeAnthropicProvider(config, env, pricing) {
           usage: {
             input_tokens: res.usage.input_tokens,
             output_tokens: res.usage.output_tokens
-          }
+          },
+          ...res.stop_reason === "max_tokens" ? { finish_reason: "length" } : res.stop_reason !== null && res.stop_reason !== void 0 ? { finish_reason: res.stop_reason } : {}
         };
       } catch (err) {
         throw normalizeProviderError(err, apiKey, ENV_VAR);
       }
     },
-    estimateCost(usage2, reportedCostUsd) {
-      return { cost_usd: resolveCost(usage2, config.model, reportedCostUsd, pricing) };
+    estimateCost(usage3, reportedCostUsd) {
+      return { cost_usd: resolveCost(usage3, config.model, reportedCostUsd, pricing) };
     }
   };
 }
@@ -680,8 +681,11 @@ function makeOpenAiCompatibleProvider(opts) {
           { max_retries: maxRetries }
         );
         const reportedCost = reportsCost ? res.usage?.cost : void 0;
+        const choice = res.choices[0];
+        const finish = choice?.error !== void 0 ? "error" : choice?.finish_reason;
         return {
-          output: res.choices[0]?.message?.content ?? "",
+          output: choice?.message?.content ?? "",
+          ...typeof finish === "string" ? { finish_reason: finish } : {},
           usage: {
             input_tokens: res.usage?.prompt_tokens ?? 0,
             output_tokens: res.usage?.completion_tokens ?? 0
@@ -692,8 +696,8 @@ function makeOpenAiCompatibleProvider(opts) {
         throw normalizeProviderError(err, apiKey, apiKeyEnv);
       }
     },
-    estimateCost(usage2, reportedCostUsd) {
-      return { cost_usd: resolveCost(usage2, config.model, reportedCostUsd, pricing) };
+    estimateCost(usage3, reportedCostUsd) {
+      return { cost_usd: resolveCost(usage3, config.model, reportedCostUsd, pricing) };
     }
   };
 }
@@ -796,8 +800,8 @@ function makeEstimateProvider(config, pricing) {
     complete: () => Promise.reject(
       new Error("The --dry-run provider only estimates cost; it never calls a model.")
     ),
-    estimateCost: (usage2, reportedCostUsd) => ({
-      cost_usd: resolveCost(usage2, config.model, reportedCostUsd, pricing)
+    estimateCost: (usage3, reportedCostUsd) => ({
+      cost_usd: resolveCost(usage3, config.model, reportedCostUsd, pricing)
     })
   };
 }
@@ -891,18 +895,115 @@ var init_embeddings = __esm({
   }
 });
 
+// src/util/canonical-json.ts
+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(value2)}`
+      );
+    }
+    return value2 === 0 ? 0 : value2;
+  }
+  if (typeof value2 === "string") {
+    return value2.normalize("NFC");
+  }
+  if (Array.isArray(value2)) {
+    return value2.map(normalizeValue);
+  }
+  if (typeof value2 === "object") {
+    const proto = Object.getPrototypeOf(value2);
+    if (proto !== null && proto !== Object.prototype) {
+      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 = value2;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = normalizeValue(obj[key]);
+    }
+    return sorted;
+  }
+  throw new Error(
+    `canonicalJson: unsupported value type: ${typeof value2}`
+  );
+}
+function canonicalJson(value2) {
+  return JSON.stringify(normalizeValue(value2));
+}
+var init_canonical_json = __esm({
+  "src/util/canonical-json.ts"() {
+    "use strict";
+    init_cjs_shims();
+  }
+});
+
+// src/util/hash.ts
+function sha256(input) {
+  return (0, import_node_crypto.createHash)("sha256").update(input, "utf8").digest("hex");
+}
+function cacheKey(inputs, policyVersion = CACHE_POLICY_VERSION) {
+  const { provider, model, temperature, max_tokens, prompt_resolved } = inputs;
+  return sha256(
+    canonicalJson({ provider, model, temperature, max_tokens, prompt_resolved, policy: policyVersion })
+  );
+}
+function configHash(config) {
+  return sha256(canonicalJson(config));
+}
+var import_node_crypto, CACHE_POLICY_VERSION;
+var init_hash = __esm({
+  "src/util/hash.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_crypto = require("crypto");
+    init_canonical_json();
+    CACHE_POLICY_VERSION = 1;
+  }
+});
+
 // src/cache/cache.ts
+function isCacheable(res) {
+  if (res.output.trim() === "") return false;
+  return res.finish_reason === void 0 || !UNCACHEABLE_FINISH.has(res.finish_reason);
+}
+function loadDatabase() {
+  try {
+    return (0, import_node_module.createRequire)(importMetaUrl)("better-sqlite3");
+  } catch {
+    if (!missingNoted) {
+      missingNoted = true;
+      console.error(
+        "plune: completion cache disabled (better-sqlite3 is not installed or failed to load). Reinstall with a C++ toolchain and Python available, or ignore: runs work without the cache."
+      );
+    }
+    return void 0;
+  }
+}
 function openCache(file, opts = {}) {
   const now = opts.now ?? Date.now;
+  const Database = loadDatabase();
+  if (Database === void 0) return new NoOpCache();
   try {
-    const db = new import_better_sqlite3.default(file);
+    const db = new Database(file);
     try {
       ensureSchema(db);
     } catch (err) {
       db.close();
       throw err;
     }
-    return new SqliteCache(db, now);
+    let stale;
+    try {
+      stale = markPolicy(db, opts.policyVersion ?? CACHE_POLICY_VERSION);
+    } catch (err) {
+      db.close();
+      throw err;
+    }
+    return new SqliteCache(db, now, stale);
   } catch {
     return new NoOpCache();
   }
@@ -917,26 +1018,45 @@ function ensureSchema(db) {
     db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("schema_version", current);
   }
 }
-var import_better_sqlite3, SCHEMA_VERSION, META_DDL, COMPLETIONS_DDL, SqliteCache, NoOpCache;
+function markPolicy(db, version) {
+  const current = String(version);
+  const stored = db.prepare("SELECT value FROM meta WHERE key = 'policy_version'").get()?.value;
+  if (stored === current) return 0;
+  return db.transaction(() => {
+    const { n } = db.prepare("SELECT COUNT(*) AS n FROM completions").get();
+    db.exec("DELETE FROM completions");
+    db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run("policy_version", current);
+    return n;
+  })();
+}
+var import_node_module, SCHEMA_VERSION, META_DDL, COMPLETIONS_DDL, UNCACHEABLE_FINISH, missingNoted, SqliteCache, NoOpCache;
 var init_cache = __esm({
   "src/cache/cache.ts"() {
     "use strict";
     init_cjs_shims();
-    import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+    import_node_module = require("module");
+    init_hash();
     SCHEMA_VERSION = 1;
     META_DDL = "CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);";
     COMPLETIONS_DDL = "CREATE TABLE IF NOT EXISTS completions (cache_key TEXT PRIMARY KEY, output TEXT NOT NULL, input_tokens INTEGER NOT NULL, output_tokens INTEGER NOT NULL, created_at INTEGER NOT NULL);";
+    UNCACHEABLE_FINISH = /* @__PURE__ */ new Set(["length", "max_tokens", "error", "content_filter", "pause_turn"]);
+    missingNoted = false;
     SqliteCache = class {
-      constructor(db, now) {
+      constructor(db, now, staleEntries) {
         this.db = db;
         this.now = now;
+        this.staleEntries = staleEntries;
       }
       db;
       now;
+      staleEntries;
       get(key, opts = {}) {
         try {
           const row = this.db.prepare("SELECT output, input_tokens, output_tokens, created_at FROM completions WHERE cache_key = ?").get(key);
           if (row === void 0) return void 0;
+          if (typeof row.output !== "string" || !Number.isFinite(row.input_tokens) || !Number.isFinite(row.output_tokens) || !Number.isFinite(row.created_at)) {
+            return void 0;
+          }
           if (opts.maxAgeMs !== void 0 && this.now() - row.created_at > opts.maxAgeMs) {
             return void 0;
           }
@@ -962,6 +1082,12 @@ var init_cache = __esm({
         } catch {
         }
       }
+      delete(key) {
+        try {
+          this.db.prepare("DELETE FROM completions WHERE cache_key = ?").run(key);
+        } catch {
+        }
+      }
       clear() {
         try {
           this.db.exec("DELETE FROM completions");
@@ -978,6 +1104,8 @@ var init_cache = __esm({
       }
       set() {
       }
+      delete() {
+      }
       clear() {
       }
       close() {
@@ -995,71 +1123,77 @@ var init_cache2 = __esm({
   }
 });
 
-// src/util/canonical-json.ts
-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(value2)}`
-      );
-    }
-    return value2 === 0 ? 0 : value2;
+// src/assertions/json-extract.ts
+function extractJson(output, mode) {
+  if (mode === "strict") {
+    return tryParse(output.trim());
   }
-  if (typeof value2 === "string") {
-    return value2.normalize("NFC");
+  const fenced = extractFencedBlock(output);
+  if (fenced !== null) {
+    const r = tryParse(fenced);
+    if (r.ok) return r;
   }
-  if (Array.isArray(value2)) {
-    return value2.map(normalizeValue);
+  for (const run of balancedRuns(output)) {
+    const r = tryParse(run);
+    if (r.ok) return r;
   }
-  if (typeof value2 === "object") {
-    const proto = Object.getPrototypeOf(value2);
-    if (proto !== null && proto !== Object.prototype) {
-      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 = value2;
-    const sorted = {};
-    for (const key of Object.keys(obj).sort()) {
-      sorted[key] = normalizeValue(obj[key]);
-    }
-    return sorted;
+  return { ok: false };
+}
+function tryParse(s) {
+  try {
+    return { ok: true, value: JSON.parse(s) };
+  } catch {
+    return { ok: false };
   }
-  throw new Error(
-    `canonicalJson: unsupported value type: ${typeof value2}`
-  );
 }
-function canonicalJson(value2) {
-  return JSON.stringify(normalizeValue(value2));
+function extractFencedBlock(s) {
+  const m = s.match(/```(?:json)?\s*\n?([\s\S]*?)```/i);
+  return m?.[1]?.trim() ?? null;
 }
-var init_canonical_json = __esm({
-  "src/util/canonical-json.ts"() {
-    "use strict";
-    init_cjs_shims();
+function* balancedRuns(s) {
+  let i = 0;
+  while (i < s.length) {
+    const rel = s.slice(i).search(/[{[]/);
+    if (rel === -1) return;
+    const start = i + rel;
+    const run = balancedFrom(s, start);
+    if (run === null) {
+      i = start + 1;
+    } else {
+      yield run;
+      i = start + run.length;
+    }
   }
-});
-
-// src/util/hash.ts
-function sha256(input) {
-  return (0, import_node_crypto.createHash)("sha256").update(input, "utf8").digest("hex");
-}
-function cacheKey(inputs) {
-  const { provider, model, temperature, max_tokens, prompt_resolved } = inputs;
-  return sha256(canonicalJson({ provider, model, temperature, max_tokens, prompt_resolved }));
 }
-function configHash(config) {
-  return sha256(canonicalJson(config));
+function balancedFrom(s, start) {
+  const open = s[start];
+  const close = open === "{" ? "}" : "]";
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < s.length; i++) {
+    const ch = s[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === open) {
+      depth++;
+    } else if (ch === close) {
+      depth--;
+      if (depth === 0) return s.slice(start, i + 1);
+    }
+  }
+  return null;
 }
-var import_node_crypto;
-var init_hash = __esm({
-  "src/util/hash.ts"() {
+var init_json_extract = __esm({
+  "src/assertions/json-extract.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_crypto = require("crypto");
-    init_canonical_json();
   }
 });
 
@@ -1157,80 +1291,6 @@ var init_contains = __esm({
   }
 });
 
-// src/assertions/json-extract.ts
-function extractJson(output, mode) {
-  if (mode === "strict") {
-    return tryParse(output.trim());
-  }
-  const fenced = extractFencedBlock(output);
-  if (fenced !== null) {
-    const r = tryParse(fenced);
-    if (r.ok) return r;
-  }
-  for (const run of balancedRuns(output)) {
-    const r = tryParse(run);
-    if (r.ok) return r;
-  }
-  return { ok: false };
-}
-function tryParse(s) {
-  try {
-    return { ok: true, value: JSON.parse(s) };
-  } catch {
-    return { ok: false };
-  }
-}
-function extractFencedBlock(s) {
-  const m = s.match(/```(?:json)?\s*\n?([\s\S]*?)```/i);
-  return m?.[1]?.trim() ?? null;
-}
-function* balancedRuns(s) {
-  let i = 0;
-  while (i < s.length) {
-    const rel = s.slice(i).search(/[{[]/);
-    if (rel === -1) return;
-    const start = i + rel;
-    const run = balancedFrom(s, start);
-    if (run === null) {
-      i = start + 1;
-    } else {
-      yield run;
-      i = start + run.length;
-    }
-  }
-}
-function balancedFrom(s, start) {
-  const open = s[start];
-  const close = open === "{" ? "}" : "]";
-  let depth = 0;
-  let inString = false;
-  let escaped = false;
-  for (let i = start; i < s.length; i++) {
-    const ch = s[i];
-    if (inString) {
-      if (escaped) escaped = false;
-      else if (ch === "\\") escaped = true;
-      else if (ch === '"') inString = false;
-      continue;
-    }
-    if (ch === '"') {
-      inString = true;
-    } else if (ch === open) {
-      depth++;
-    } else if (ch === close) {
-      depth--;
-      if (depth === 0) return s.slice(start, i + 1);
-    }
-  }
-  return null;
-}
-var init_json_extract = __esm({
-  "src/assertions/json-extract.ts"() {
-    "use strict";
-    init_cjs_shims();
-  }
-});
-
 // src/assertions/json-schema.ts
 var import_ajv, jsonSchema;
 var init_json_schema = __esm({
@@ -1692,6 +1752,11 @@ var init_results = __esm({
 });
 
 // src/orchestrator/run.ts
+function answerParses(output, assertions) {
+  return assertions.every(
+    (a) => a.type !== "json-schema" || extractJson(output, a.extract ?? "auto").ok
+  );
+}
 function resolvePrompt(template, vars) {
   return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (_match, key) => {
     if (!(key in vars)) {
@@ -1716,28 +1781,51 @@ async function runRow(p) {
   const maxTokens = p.providerConfig.max_tokens ?? DEFAULT_MAX_TOKENS2;
   if (p.dryRun) {
     const est = estimateUsage(prompt5, maxTokens);
-    const usage3 = { ...est, cost_usd: p.provider.estimateCost(est).cost_usd };
-    return { vars: p.row.vars, output: null, cached: false, usage: usage3, assertions: [] };
-  }
-  const key = cacheKey({
-    provider: p.providerConfig.type,
-    model: p.providerConfig.model,
-    temperature: temperature ?? 0,
-    max_tokens: maxTokens,
-    prompt_resolved: prompt5
-  });
+    const usage4 = { ...est, cost_usd: p.provider.estimateCost(est).cost_usd };
+    return { vars: p.row.vars, output: null, cached: false, usage: usage4, assertions: [] };
+  }
+  const key = cacheKey(
+    {
+      provider: p.providerConfig.type,
+      model: p.providerConfig.model,
+      temperature: temperature ?? 0,
+      max_tokens: maxTokens,
+      prompt_resolved: prompt5
+    },
+    p.policyVersion
+  );
   let output;
-  let usage2;
+  let usage3;
   let cached = false;
-  const hit = p.noCache ? void 0 : p.cache.get(key);
+  let cacheSaved;
+  let hit = p.noCache ? void 0 : p.cache.get(key, p.cacheMaxAgeMs !== void 0 ? { maxAgeMs: p.cacheMaxAgeMs } : {});
+  if (hit !== void 0 && !answerParses(hit.output, p.assertions)) {
+    if (p.cacheStrict !== true) p.cache.delete(key);
+    hit = void 0;
+  }
+  if (hit === void 0 && p.cacheStrict === true) {
+    return {
+      vars: p.row.vars,
+      output: null,
+      cached: false,
+      latency_ms: p.now() - t0,
+      error: { code: CACHE_MISS_CODE, message: "no usable cache entry (--cache-strict)" },
+      assertions: []
+    };
+  }
   if (hit !== void 0) {
     output = hit.output;
     cached = true;
-    usage2 = {
+    usage3 = {
       input_tokens: hit.usage.input_tokens,
       output_tokens: hit.usage.output_tokens,
       cost_usd: 0
     };
+    cacheSaved = {
+      input_tokens: hit.usage.input_tokens,
+      output_tokens: hit.usage.output_tokens,
+      cost_usd: p.provider.estimateCost(hit.usage).cost_usd
+    };
   } else {
     try {
       const res = await p.provider.complete({
@@ -1748,14 +1836,16 @@ async function runRow(p) {
         prompt_resolved: prompt5
       });
       output = res.output;
-      usage2 = {
+      usage3 = {
         input_tokens: res.usage.input_tokens,
         output_tokens: res.usage.output_tokens,
         // Prefer the provider-reported actual cost (res.cost_usd) when present; resolveCost still
         // lets a config pricing override win, else falls back to the table estimate (ADR-PRC01).
         cost_usd: p.provider.estimateCost(res.usage, res.cost_usd).cost_usd
       };
-      if (!p.noCache) p.cache.set(key, res);
+      if (!p.noCache && isCacheable(res) && answerParses(res.output, p.assertions)) {
+        p.cache.set(key, res);
+      }
     } catch (err) {
       return {
         vars: p.row.vars,
@@ -1794,13 +1884,14 @@ async function runRow(p) {
       break;
     }
   }
-  const finalUsage = { ...usage2, cost_usd: usage2.cost_usd + judgeCost };
+  const finalUsage = { ...usage3, cost_usd: usage3.cost_usd + judgeCost };
   return {
     vars: p.row.vars,
     output,
     cached,
     usage: finalUsage,
     latency_ms: p.now() - t0,
+    ...cacheSaved !== void 0 ? { cache_saved: cacheSaved } : {},
     ...assertionError !== void 0 ? { error: assertionError } : {},
     assertions: records
   };
@@ -1835,19 +1926,41 @@ function summarize(evals, durationMs) {
     cost_usd: 0,
     duration_ms: durationMs
   };
+  const cache = {
+    from_cache: 0,
+    from_model: 0,
+    missed: 0,
+    errored: 0,
+    saved: { input_tokens: 0, output_tokens: 0, cost_usd: 0 }
+  };
   for (const ev of evals) {
     for (const row of ev.rows) {
       summary.total += 1;
       summary[rowStatus(row)] += 1;
       summary.cost_usd += row.usage?.cost_usd ?? 0;
+      if (row.cached) {
+        cache.from_cache += 1;
+        cache.saved.input_tokens += row.cache_saved?.input_tokens ?? 0;
+        cache.saved.output_tokens += row.cache_saved?.output_tokens ?? 0;
+        cache.saved.cost_usd += row.cache_saved?.cost_usd ?? 0;
+      } else if (row.error?.code === CACHE_MISS_CODE) cache.missed += 1;
+      else if (row.output !== null) cache.from_model += 1;
+      else if (row.error !== void 0) cache.errored += 1;
     }
   }
-  return summary;
+  return { ...summary, cache };
 }
 async function runOrchestration(config, options, deps) {
+  const noCache = options.noCache ?? false;
+  const cacheStrict = options.cacheStrict ?? false;
+  if (noCache && cacheStrict) {
+    throw new RunConfigError("--no-cache and --cache-strict cannot be used together");
+  }
+  if (noCache && options.cacheMaxAgeMs !== void 0) {
+    throw new RunConfigError("--no-cache and --cache-max-age cannot be used together");
+  }
   const started = deps.now();
   const dryRun = options.dryRun ?? false;
-  const noCache = options.noCache ?? false;
   const evalResults = [];
   const prepared = selectEvals(config.evals, options.only).map((ev) => {
     const template = resolveTemplate(ev, deps.baseDir);
@@ -1874,7 +1987,9 @@ async function runOrchestration(config, options, deps) {
         cache: deps.cache,
         now: deps.now,
         dryRun,
-        noCache
+        noCache,
+        cacheStrict,
+        ...options.cacheMaxAgeMs !== void 0 ? { cacheMaxAgeMs: options.cacheMaxAgeMs } : {}
       })
     );
     const passed = rowResults.every((r) => rowStatus(r) === "passed");
@@ -1893,7 +2008,7 @@ async function runOrchestration(config, options, deps) {
     evals: evalResults
   };
 }
-var fs3, path3, DEFAULT_MAX_TOKENS2, PLUNE_VERSION, RunConfigError;
+var fs3, path3, DEFAULT_MAX_TOKENS2, PLUNE_VERSION, RunConfigError, CACHE_MISS_CODE;
 var init_run = __esm({
   "src/orchestrator/run.ts"() {
     "use strict";
@@ -1901,6 +2016,8 @@ var init_run = __esm({
     fs3 = __toESM(require("fs"), 1);
     path3 = __toESM(require("path"), 1);
     init_hash();
+    init_json_extract();
+    init_cache();
     init_assertions();
     init_judge();
     init_concurrency();
@@ -1915,20 +2032,29 @@ var init_run = __esm({
         this.name = "RunConfigError";
       }
     };
+    CACHE_MISS_CODE = "CACHE_MISS";
   }
 });
 
 // src/orchestrator/exit-code.ts
+function cacheMissRows(result) {
+  return result.evals.flatMap(
+    (ev) => ev.rows.filter((r) => r.error?.code === CACHE_MISS_CODE).map((r) => `${ev.id} ${JSON.stringify(r.vars)}`)
+  );
+}
 function exitCodeFor(result) {
   const { failed, errored } = result.summary;
   if (failed > 0) return 1;
   if (errored > 0) return 2;
   return 0;
 }
+var CACHE_STRICT_EXIT;
 var init_exit_code = __esm({
   "src/orchestrator/exit-code.ts"() {
     "use strict";
     init_cjs_shims();
+    init_run();
+    CACHE_STRICT_EXIT = 5;
   }
 });
 
@@ -1953,8 +2079,11 @@ var init_dataset = __esm({
 // src/orchestrator/index.ts
 var orchestrator_exports = {};
 __export(orchestrator_exports, {
+  CACHE_MISS_CODE: () => CACHE_MISS_CODE,
+  CACHE_STRICT_EXIT: () => CACHE_STRICT_EXIT,
   RunConfigError: () => RunConfigError,
   buildJudge: () => buildJudge,
+  cacheMissRows: () => cacheMissRows,
   exitCodeFor: () => exitCodeFor,
   loadDataset: () => loadDataset,
   mapLimit: () => mapLimit,
@@ -2013,6 +2142,11 @@ async function handleRun(options, depsFactory) {
   const factory = depsFactory ?? ((c, d) => buildRealDeps(c, d, options.dryRun));
   const deps = factory(config, baseDir);
   try {
+    const stale = deps.cache.staleEntries ?? 0;
+    if (stale > 0) {
+      process.stderr.write(`cache policy changed, ${stale} entries are stale (dropped)
+`);
+    }
     const result = await runOrchestration(
       config,
       {
@@ -2020,7 +2154,9 @@ async function handleRun(options, depsFactory) {
         ...options.only !== void 0 ? { only: options.only } : {},
         ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {},
         ...options.noCache !== void 0 ? { noCache: options.noCache } : {},
-        ...options.bail !== void 0 ? { bail: options.bail } : {}
+        ...options.bail !== void 0 ? { bail: options.bail } : {},
+        ...options.cacheStrict === true ? { cacheStrict: true } : {},
+        ...options.cacheMaxAgeMs !== void 0 ? { cacheMaxAgeMs: options.cacheMaxAgeMs } : {}
       },
       deps
     );
@@ -2045,6 +2181,7 @@ var init_run2 = __esm({
     init_cache2();
     init_orchestrator();
     NOOP_CACHE = { get: () => void 0, set: () => {
+    }, delete: () => {
     }, clear: () => {
     }, close: () => {
     } };
@@ -2104,6 +2241,15 @@ function renderConsole(result, opts = {}) {
   lines.push(
     `${passedTxt} \xB7 ${failedTxt} \xB7 ${erroredTxt}${blockedTxt}${skippedTxt} \xB7 ${summary.total} total \xB7 $${summary.cost_usd.toFixed(4)} \xB7 ${summary.duration_ms}ms`
   );
+  const c = summary.cache;
+  if (c !== void 0 && c.from_cache + c.from_model + c.missed > 0) {
+    const missedTxt = c.missed > 0 ? ` \xB7 ${s.yellow(`${c.missed} missed`)}` : "";
+    lines.push(
+      s.dim(
+        `cache: ${c.from_cache} from cache \xB7 ${c.from_model} from model${missedTxt} \xB7 saved ${c.saved.input_tokens + c.saved.output_tokens} tokens, $${c.saved.cost_usd.toFixed(4)}`
+      )
+    );
+  }
   lines.push("");
   for (const ev of result.evals) {
     const mark = ev.passed ? s.green("PASS") : s.red("FAIL");
@@ -2707,7 +2853,14 @@ function repoRootOf(dir, stopAt) {
     if (here === stopAt || (0, import_node_path2.dirname)(here) === here) return void 0;
   }
 }
-function errorContextOf(attempt, home = (0, import_node_os2.homedir)()) {
+function errorContextFields(attempt, home = (0, import_node_os2.homedir)()) {
+  const { text: text2, omitted: omitted2 } = cutErrorContext(attempt, home);
+  return {
+    ...text2 !== "" ? { errorContext: text2 } : {},
+    ...omitted2 > 0 ? { errorContextOmitted: omitted2 } : {}
+  };
+}
+function cutErrorContext(attempt, home) {
   const text2 = attempt.errors.map((e) => e.text).filter((t) => t !== "").join("\n\n");
   return cut(machineless(text2, attempt.repoRoot, home));
 }
@@ -2733,7 +2886,7 @@ function pathIn(path17) {
   return new RegExp(`${url}${escaped}`, /^[A-Za-z]:$/.test(parts[0]) ? "gi" : "g");
 }
 function cut(text2) {
-  if (jsonBytes(text2) <= TEXT_LIMIT) return text2;
+  if (jsonBytes(text2) <= TEXT_LIMIT) return { text: text2, omitted: 0 };
   const lines = text2.split("\n");
   const size = lines.map((line) => jsonBytes(line) + 2);
   const budget = TEXT_LIMIT - jsonBytes(omitted(lines.length));
@@ -2742,7 +2895,8 @@ function cut(text2) {
   let tail = lines.length;
   while (head < tail && used + size[head] <= budget / 2) used += size[head++];
   while (tail > head && used + size[tail - 1] <= budget) used += size[--tail];
-  return [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n");
+  const kept = [...lines.slice(0, head), ...lines.slice(tail)].join("\n");
+  return { text: [...lines.slice(0, head), omitted(tail - head), ...lines.slice(tail)].join("\n"), omitted: text2.length - kept.length };
 }
 function chosen({ status, errors }) {
   if (status === "timedOut") {
@@ -3903,7 +4057,7 @@ async function handleRunStart(options = {}) {
     kind: options.kind ?? "automated",
     externalKey,
     // The same name the reporter would give it; `PLUNE_RUN_TITLE` replaces it, as everywhere.
-    title: env.config.title ?? defaultRunTitle()
+    title: options.name ?? env.config.title ?? defaultRunTitle()
   });
   if (!out.ok) throw new RunCommandError(`Could not start the run \u2014 ${out.detail || out.kind}.`);
   const result = {
@@ -4122,6 +4276,7 @@ var init_run_result_schema = __esm({
       latency_ms: import_zod3.z.number().optional(),
       error: runErrorSchema.optional(),
       assertions: import_zod3.z.array(assertionResultRecordSchema2),
+      cache_saved: import_zod3.z.object({ input_tokens: import_zod3.z.number(), output_tokens: import_zod3.z.number(), cost_usd: import_zod3.z.number() }).optional(),
       /** ADR 0045. Optional and additive — the same enum the platform validates on `POST /v1/runs`. */
       inconclusive: import_zod3.z.enum(ROW_INCONCLUSIVE).optional()
     });
@@ -4134,7 +4289,14 @@ var init_run_result_schema = __esm({
       blocked: import_zod3.z.number().optional(),
       skipped: import_zod3.z.number().optional(),
       cost_usd: import_zod3.z.number(),
-      duration_ms: import_zod3.z.number()
+      duration_ms: import_zod3.z.number(),
+      cache: import_zod3.z.object({
+        from_cache: import_zod3.z.number(),
+        from_model: import_zod3.z.number(),
+        missed: import_zod3.z.number(),
+        errored: import_zod3.z.number(),
+        saved: import_zod3.z.object({ input_tokens: import_zod3.z.number(), output_tokens: import_zod3.z.number(), cost_usd: import_zod3.z.number() })
+      }).optional()
     });
     evalResultSchema = import_zod3.z.object({
       id: import_zod3.z.string(),
@@ -4309,6 +4471,7 @@ __export(plan_exports, {
   grepFragment: () => grepFragment,
   handlePlanGrep: () => handlePlanGrep,
   handleRunGrep: () => handleRunGrep,
+  platformGet: () => platformGet,
   runGrepSummary: () => runGrepSummary
 });
 function grepFragment(c) {
@@ -4853,7 +5016,7 @@ function pendingOf(r, retry, ctx) {
     })),
     testFile: ""
   };
-  const errorContext = errorContextOf(attempt);
+  const errorContext = errorContextFields(attempt);
   const failure = FAILED.has(status) ? failureOf(attempt) : void 0;
   const pkg2 = labelOf(r, "package");
   const where = (key.includes("#") ? key.split("#")[0] : pkg2)?.replace(/^[A-Za-z][A-Za-z0-9_-]+:(?![\\/])/, "");
@@ -4877,7 +5040,7 @@ function pendingOf(r, retry, ctx) {
         retry
       }
     } : {},
-    ...errorContext !== "" ? { errorContext } : {},
+    ...errorContext,
     ...failure !== void 0 ? { failure } : {},
     ...files.length > 0 ? { files } : {}
   };
@@ -5207,7 +5370,7 @@ function pendingFrom(spec, test, result, file, titles, ctx) {
   const stated = statedIdOf(test, spec.title ?? "");
   const expected = test.expectedStatus;
   const attempt = attemptOf(result, file, ctx);
-  const errorContext = errorContextOf(attempt);
+  const errorContext = errorContextFields(attempt);
   const failure = NOT_FAILED.has(attempt.status) ? void 0 : failureOf(attempt);
   const files = filesOf(attempt);
   const keys = [
@@ -5237,7 +5400,7 @@ function pendingFrom(spec, test, result, file, titles, ctx) {
         ...result.workerIndex !== void 0 ? { worker: String(result.workerIndex) } : {}
       }
     } : {},
-    ...errorContext !== "" ? { errorContext } : {},
+    ...errorContext,
     ...failure !== void 0 ? { failure } : {},
     ...files.length > 0 ? { files } : {}
   };
@@ -5420,6 +5583,7 @@ async function handleRunImport(options) {
         token,
         ...options.fetchImpl !== void 0 ? { fetchImpl: options.fetchImpl } : {},
         ...options.key !== void 0 ? { externalKey: options.key } : {},
+        ...options.name !== void 0 ? { title: options.name } : {},
         ...options.create === true ? { offerDiscovered: true } : {},
         ...options.uploadConcurrency !== void 0 ? { uploadConcurrency: options.uploadConcurrency } : {},
         kind: "automated",
@@ -6353,12 +6517,18 @@ __export(requirements_import_exports, {
   MAX_MARKDOWN_BYTES: () => MAX_MARKDOWN_BYTES,
   RequirementsImportError: () => RequirementsImportError,
   buildImportBody: () => buildImportBody,
+  cut: () => cut2,
+  flat: () => flat,
   formatDiscover: () => formatDiscover,
   formatReport: () => formatReport2,
   handleRequirementsImport: () => handleRequirementsImport,
   parseMap: () => parseMap,
   parseTableSpec: () => parseTableSpec,
-  reportRequirementsImportFailure: () => reportRequirementsImportFailure
+  plural: () => plural,
+  readMarkdown: () => readMarkdown,
+  refusal: () => refusal,
+  reportRequirementsImportFailure: () => reportRequirementsImportFailure,
+  resolveProject: () => resolveProject
 });
 function parseMap(flag2, raw) {
   const out = {};
@@ -6645,6 +6815,321 @@ var init_requirements_import = __esm({
   }
 });
 
+// src/cli/commands/requirements-links.ts
+var requirements_links_exports = {};
+__export(requirements_links_exports, {
+  buildLinksBody: () => buildLinksBody,
+  formatLinks: () => formatLinks,
+  formatLinksDiscover: () => formatLinksDiscover,
+  handleRequirementsLinks: () => handleRequirementsLinks
+});
+function buildLinksBody(f) {
+  if (f.table === void 0 && f.requirementColumn === void 0 && f.testColumn === void 0 && f.separator === void 0) return null;
+  if (f.table === void 0) return usage2("--requirement-column, --test-column and --separator need --table <n>. Run without flags to see which tables the file has.");
+  if (!/^\d+$/.test(f.table)) usage2(`--table is the number of the table in the list (0, 1, ...), not "${f.table}".`);
+  if (f.requirementColumn === void 0 || f.requirementColumn.trim() === "") usage2("--table needs --requirement-column <header> (the column with the requirement keys).");
+  if (f.testColumn === void 0 || f.testColumn.trim() === "") usage2("--table needs --test-column <header> (the column with the test titles or paths).");
+  const body = { table: Number(f.table), requirementColumn: f.requirementColumn, testColumn: f.testColumn };
+  if (f.separator !== void 0) {
+    if (f.separator.length < 1 || f.separator.length > 3) usage2(`--separator is 1 to 3 characters, not "${f.separator}".`);
+    body["requirementSeparator"] = f.separator;
+  }
+  return body;
+}
+async function handleRequirementsLinks(deps) {
+  const apiUrl = resolveApiUrl(deps.apiUrl);
+  const mapping = buildLinksBody(deps);
+  const markdown = readMarkdown(deps.cwd ?? process.cwd(), deps.file);
+  const token = (deps.loadToken ?? loadToken)();
+  if (token === null) throw new RequirementsImportError('Not logged in. Run "plune login" first, or set PLUNE_TOKEN.', 2);
+  const client = createClient({ apiUrl, token, ...deps.fetchImpl !== void 0 ? { fetchImpl: deps.fetchImpl } : {} });
+  const projectId = await resolveProject(client, deps.project, apiUrl);
+  const base = `/v1/projects/${encodeURIComponent(projectId)}/requirements/import`;
+  if (mapping === null) {
+    const out2 = await client.post(`${base}/discover`, { markdown });
+    if (!out2.ok) throw refusal(out2, apiUrl, projectId);
+    return { step: "discover", result: out2.body };
+  }
+  const out = await client.post(`${base}/links`, { markdown, dryRun: deps.yes !== true, ...mapping });
+  if (!out.ok) throw refusal(out, apiUrl, projectId);
+  return { step: "links", report: out.body };
+}
+function formatLinksDiscover(file, r) {
+  const out = [`${file}: ${plural(r.tables.length, "table")}`, ""];
+  if (r.tables.length === 0) out.push("  (none)");
+  for (const t of r.tables) {
+    const mark = t.unreadable !== void 0 ? `   cannot be read: ${t.unreadable}` : "";
+    out.push(`  #${t.index}  line ${t.line}  ${t.heading === null ? "(no heading)" : `"${flat(t.heading)}"`}  ${cut2(t.headers.map(flat).join(" | "), 100)}  ${plural(t.rowCount, "row")}${mark}`);
+  }
+  if (r.truncated) out.push("", "The file has more tables than are listed here.");
+  out.push("", "Pick the matrix and name its two columns (a dry run, nothing is written):", `  plune requirements links ${file} --table <n> --requirement-column <header> --test-column <header>`);
+  return out.join("\n") + "\n";
+}
+function formatLinks(report) {
+  const s = report.summary;
+  const out = [`link ${s.link} \xB7 unchanged ${s.unchanged} \xB7 unmatched ${s.unmatched}`];
+  for (const action of ["unmatched", "link", "unchanged"]) {
+    const rows = report.items.filter((i) => i.action === action);
+    if (rows.length === 0) continue;
+    out.push("", `${action} (${rows.length})`);
+    for (const i of rows.slice(0, SHOWN2)) {
+      out.push(`  line ${i.line}  ${i.key === "" ? "-" : i.key}  ->  ${i.test === "" ? "-" : cut2(flat(i.test), 80)}  - ${flat(i.reason)}`);
+    }
+    if (rows.length > SHOWN2) out.push(`  ... and ${rows.length - SHOWN2} more (--json lists every row)`);
+  }
+  out.push("", report.applied ? `applied \u2014 ${plural(s.link, "link")} created.` : "dry run \u2014 nothing was written; add --yes to apply");
+  return out.join("\n") + "\n";
+}
+var usage2, SHOWN2;
+var init_requirements_links = __esm({
+  "src/cli/commands/requirements-links.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_client();
+    init_api_url();
+    init_credentials();
+    init_requirements_import();
+    usage2 = (message) => {
+      throw new RequirementsImportError(message, 2);
+    };
+    SHOWN2 = 50;
+  }
+});
+
+// src/cli/commands/verify.ts
+var verify_exports = {};
+__export(verify_exports, {
+  compare: () => compare,
+  formatVerify: () => formatVerify,
+  handleVerify: () => handleVerify,
+  loadSources: () => loadSources,
+  testsOfListing: () => testsOfListing
+});
+function testsOfListing(listing) {
+  const found = /* @__PURE__ */ new Map();
+  const walk2 = (suite, titles) => {
+    for (const spec of suite.specs ?? []) {
+      const annotated = spec.tests?.flatMap((t) => t.annotations ?? []).find(
+        (a) => a.type === "PluneId" && a.description !== void 0 && a.description !== ""
+      )?.description;
+      const id = annotated ?? TOKEN4.exec(spec.title)?.[1];
+      const pathTitle = [...titles, spec.title].join("#");
+      if (!found.has(pathTitle))
+        found.set(pathTitle, { pathTitle, ...id === void 0 ? {} : { id } });
+    }
+    for (const child of suite.suites ?? []) walk2(child, [...titles, child.title]);
+  };
+  for (const file of listing.suites ?? []) walk2(file, [file.title.replace(/\\/g, "/")]);
+  return [...found.values()];
+}
+function compare(code, cases) {
+  const live = cases.filter((c) => c.type === "automated" && c.state !== "deprecated");
+  const byPath = /* @__PURE__ */ new Map();
+  for (const c of live)
+    for (const k of c.externalKeys ?? []) if (k.kind === "path-title") byPath.set(k.value, c);
+  const byId = new Map(live.map((c) => [c.id, c]));
+  const seen = /* @__PURE__ */ new Set();
+  const onlyInCode = [];
+  for (const t of code) {
+    const hit = (t.id === void 0 ? void 0 : byId.get(t.id)) ?? byPath.get(t.pathTitle);
+    if (hit === void 0) onlyInCode.push({ pathTitle: t.pathTitle });
+    else seen.add(hit.id);
+  }
+  return {
+    matched: seen.size,
+    onlyInPlatform: live.filter((c) => !seen.has(c.id)).map((c) => ({ id: c.id, title: c.title, state: c.state, detached: c.state === "detached" })),
+    onlyInCode
+  };
+}
+function runPlaywrightList(args, cwd) {
+  try {
+    return (0, import_node_child_process3.execFileSync)("npx", ["playwright", "test", ...args], {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 256 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: process.platform === "win32"
+    });
+  } catch (err) {
+    const stderr = err.stderr?.trim();
+    throw new SyncFileError(`could not list the Playwright tests${stderr ? `: ${stderr}` : ""}`);
+  }
+}
+async function loadSources(deps) {
+  const get = platformGet(deps);
+  let raw;
+  if (deps.from !== void 0) {
+    try {
+      raw = (0, import_node_fs8.readFileSync)(deps.from, "utf8");
+    } catch {
+      throw new SyncFileError(`cannot read ${deps.from}`);
+    }
+  } else {
+    const args = [
+      "--list",
+      "--reporter=json",
+      ...deps.playwrightConfig === void 0 ? [] : ["--config", deps.playwrightConfig]
+    ];
+    raw = (deps.list ?? runPlaywrightList)(args, deps.cwd ?? process.cwd());
+  }
+  let listing;
+  try {
+    listing = JSON.parse(raw);
+  } catch {
+    throw new SyncFileError("the Playwright listing is not JSON");
+  }
+  const cases = [];
+  let cursor = null;
+  do {
+    const page = await get(
+      `/v1/test-cases?type=automated&stability=0&limit=200${cursor === null ? "" : `&cursor=${cursor}`}`
+    );
+    cases.push(...page.testCases);
+    cursor = page.nextCursor;
+  } while (cursor !== null);
+  return { code: testsOfListing(listing), cases };
+}
+async function handleVerify(deps) {
+  const { code, cases } = await loadSources(deps);
+  return compare(code, cases);
+}
+function formatVerify(r) {
+  const lines = [];
+  if (r.onlyInPlatform.length > 0) {
+    lines.push(`In Plune, not in the code (${r.onlyInPlatform.length}):`);
+    for (const c of r.onlyInPlatform) {
+      lines.push(
+        `  ${c.id}  ${c.title}  [${c.detached ? "already detached" : `${c.state} \u2014 a full run would detach it`}]`
+      );
+    }
+  }
+  if (r.onlyInCode.length > 0) {
+    lines.push(`In the code, not in Plune (${r.onlyInCode.length}):`);
+    for (const t of r.onlyInCode) lines.push(`  ${t.pathTitle}`);
+  }
+  lines.push(
+    r.onlyInPlatform.length + r.onlyInCode.length === 0 ? `No drift: ${r.matched} case(s) match the code.` : `${r.matched} matched. Nothing was changed.`
+  );
+  return lines.join("\n") + "\n";
+}
+var import_node_child_process3, import_node_fs8, TOKEN4;
+var init_verify = __esm({
+  "src/cli/commands/verify.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_child_process3 = require("child_process");
+    import_node_fs8 = require("fs");
+    init_plan();
+    init_sync();
+    TOKEN4 = /@P([A-Za-z0-9_-]+)/;
+  }
+});
+
+// src/cli/commands/ids.ts
+var ids_exports = {};
+__export(ids_exports, {
+  DEFAULT_IDS_FILE: () => DEFAULT_IDS_FILE,
+  formatIds: () => formatIds,
+  handleIds: () => handleIds,
+  planIds: () => planIds,
+  readMap: () => readMap,
+  serializeMap: () => serializeMap
+});
+function readMap(file) {
+  if (!(0, import_node_fs9.existsSync)(file)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs9.readFileSync)(file, "utf8"));
+  } catch {
+    throw new SyncFileError(`${file} is not valid JSON; fix or remove it, nothing was written`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || Object.values(parsed).some((v) => typeof v !== "string" || v === ""))
+    throw new SyncFileError(
+      `${file} must be an object of path-title to case id strings; nothing was written`
+    );
+  return parsed;
+}
+function planIds(code, cases, current) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const c of cases)
+    if (c.type === "automated" && c.state !== "deprecated") {
+      for (const k of c.externalKeys ?? []) if (k.kind === "path-title") byPath.set(k.value, c);
+    }
+  const added = {};
+  const noCase = [];
+  let covered = 0;
+  for (const t of code) {
+    if (t.id !== void 0 || current[t.pathTitle] !== void 0) covered++;
+    else {
+      const hit = byPath.get(t.pathTitle);
+      if (hit === void 0) noCase.push(t.pathTitle);
+      else added[t.pathTitle] = hit.id;
+    }
+  }
+  const inCode = new Set(code.map((t) => t.pathTitle));
+  return {
+    added,
+    covered,
+    noCase: noCase.sort(compareKeys),
+    orphaned: Object.keys(current).filter((k) => !inCode.has(k)).sort(compareKeys)
+  };
+}
+function serializeMap(map) {
+  const sorted = {};
+  for (const k of Object.keys(map).sort(compareKeys)) sorted[k] = map[k];
+  return JSON.stringify(sorted, null, 2) + "\n";
+}
+async function handleIds(deps) {
+  const file = deps.file ?? DEFAULT_IDS_FILE;
+  const current = readMap(file);
+  const { code, cases } = await loadSources(deps);
+  const plan = planIds(code, cases, current);
+  let written = false;
+  if (deps.write === true && Object.keys(plan.added).length > 0) {
+    try {
+      (0, import_node_fs9.mkdirSync)((0, import_node_path5.dirname)(file), { recursive: true });
+      (0, import_node_fs9.writeFileSync)(file, serializeMap({ ...current, ...plan.added }));
+    } catch {
+      throw new SyncFileError(`cannot write ${file}`);
+    }
+    written = true;
+  }
+  return { file, ...plan, written };
+}
+function formatIds(r, write) {
+  const n = Object.keys(r.added).length;
+  const lines = [];
+  if (n > 0) {
+    lines.push(`${write ? "Added to" : "Would add to"} ${r.file} (${n}):`);
+    for (const k of Object.keys(r.added).sort(compareKeys)) lines.push(`  ${k}  ->  ${r.added[k]}`);
+  }
+  if (r.noCase.length > 0) {
+    lines.push(`In the code, no case in Plune yet, nothing to write (${r.noCase.length}):`);
+    for (const k of r.noCase) lines.push(`  ${k}`);
+  }
+  if (r.orphaned.length > 0) {
+    lines.push(`In ${r.file}, test no longer in the code, kept (${r.orphaned.length}):`);
+    for (const k of r.orphaned) lines.push(`  ${k}`);
+  }
+  lines.push(
+    n === 0 ? `Nothing to write: ${r.covered} test(s) already have an id.` : write ? `${r.covered} already had an id. ${r.file} written.` : `${r.covered} already had an id. Dry run: nothing was written; add --write.`
+  );
+  return lines.join("\n") + "\n";
+}
+var import_node_fs9, import_node_path5, DEFAULT_IDS_FILE, compareKeys;
+var init_ids = __esm({
+  "src/cli/commands/ids.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_fs9 = require("fs");
+    import_node_path5 = require("path");
+    init_verify();
+    init_sync();
+    DEFAULT_IDS_FILE = "plune/ids.json";
+    compareKeys = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+  }
+});
+
 // src/cli.ts
 var cli_exports = {};
 __export(cli_exports, {
@@ -6654,11 +7139,25 @@ module.exports = __toCommonJS(cli_exports);
 init_cjs_shims();
 init_api_url();
 var import_commander = require("commander");
-var import_node_fs8 = require("fs");
-var import_node_path5 = require("path");
+var import_node_fs10 = require("fs");
+var import_node_path6 = require("path");
 var import_node_url = require("url");
-var __dirname = (0, import_node_path5.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
-var pkg = JSON.parse((0, import_node_fs8.readFileSync)((0, import_node_path5.join)(__dirname, "..", "package.json"), "utf-8"));
+
+// src/util/duration.ts
+init_cjs_shims();
+var UNIT_MS = { ms: 1, s: 1e3, m: 6e4, h: 36e5, d: 864e5 };
+function parseDuration(text2) {
+  const m = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)?$/.exec(text2.trim());
+  const ms = m === null ? NaN : Number(m[1]) * UNIT_MS[m[2] ?? "ms"];
+  if (!Number.isFinite(ms) || ms <= 0) {
+    throw new Error(`Invalid duration "${text2}" (use e.g. 90s, 15m, 12h, 7d)`);
+  }
+  return ms;
+}
+
+// src/cli.ts
+var __dirname = (0, import_node_path6.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl));
+var pkg = JSON.parse((0, import_node_fs10.readFileSync)((0, import_node_path6.join)(__dirname, "..", "package.json"), "utf-8"));
 function toFormat(s) {
   return s === "json" || s === "markdown" ? s : "console";
 }
@@ -6667,7 +7166,7 @@ function shouldColor(outputPath) {
 }
 function writeReport(text2, outputPath) {
   if (outputPath !== void 0) {
-    (0, import_node_fs8.writeFileSync)(outputPath, text2);
+    (0, import_node_fs10.writeFileSync)(outputPath, text2);
   } else {
     process.stdout.write(text2 + "\n");
   }
@@ -6712,7 +7211,7 @@ function createProgram() {
   program.hook("preAction", async (_program, action) => {
     const { loadEnv: loadEnv2 } = await Promise.resolve().then(() => (init_env(), env_exports));
     const { config } = action.optsWithGlobals();
-    if (config !== void 0) loadEnv2((0, import_node_path5.dirname)((0, import_node_path5.resolve)(config)));
+    if (config !== void 0) loadEnv2((0, import_node_path6.dirname)((0, import_node_path6.resolve)(config)));
     loadEnv2(process.cwd());
   });
   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(
@@ -6720,13 +7219,17 @@ function createProgram() {
     "Run a subset by eval id or tag (repeatable)",
     (val, prev) => [...prev, val],
     []
-  ).option("--concurrency <n>", "Override provider concurrency", (v) => parseInt(v, 10)).option("--no-cache", "Bypass the local cache for this run").option("--bail", "Stop after the first failing eval", false).option("--format <fmt>", "console | json | markdown", "console").option("-o, --output <path>", "Write the report to a file instead of stdout").action(
+  ).option("--concurrency <n>", "Override provider concurrency", (v) => parseInt(v, 10)).option("--no-cache", "Bypass the local cache for this run").option(
+    "--cache-strict",
+    "Every row must be in the cache: no model calls for completions; a miss ends the run with exit 5 and lists the rows",
+    false
+  ).option("--cache-max-age <duration>", "Treat cache entries older than this as a miss (e.g. 90s, 15m, 12h, 7d)").option("--bail", "Stop after the first failing eval", false).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 configPath = globals.config;
       const [
         { handleRun: handleRun2 },
-        { exitCodeFor: exitCodeFor2, RunConfigError: RunConfigError2 },
+        { exitCodeFor: exitCodeFor2, cacheMissRows: cacheMissRows2, CACHE_STRICT_EXIT: CACHE_STRICT_EXIT2, RunConfigError: RunConfigError2 },
         { renderReport: renderReport2 },
         { ConfigNotFoundError: ConfigNotFoundError2, ConfigValidationError: ConfigValidationError2, YamlParseError: YamlParseError2 },
         { AuthError: AuthError2 }
@@ -6738,13 +7241,36 @@ function createProgram() {
         Promise.resolve().then(() => (init_errors2(), errors_exports2))
       ]);
       try {
+        if (options.cache === false && options.cacheMaxAge !== void 0) {
+          process.stderr.write("--no-cache and --cache-max-age cannot be used together\n");
+          process.exit(2);
+          return;
+        }
+        if (options.cache === false && options.cacheStrict) {
+          process.stderr.write("--no-cache and --cache-strict cannot be used together\n");
+          process.exit(2);
+          return;
+        }
+        let cacheMaxAgeMs;
+        if (options.cacheMaxAge !== void 0) {
+          try {
+            cacheMaxAgeMs = parseDuration(options.cacheMaxAge);
+          } catch (err) {
+            process.stderr.write(`--cache-max-age: ${err.message}
+`);
+            process.exit(2);
+            return;
+          }
+        }
         const result = await handleRun2({
           dryRun: options.dryRun,
           ...configPath !== void 0 ? { configPath } : {},
           ...options.only.length > 0 ? { only: options.only } : {},
           ...typeof options.concurrency === "number" && Number.isFinite(options.concurrency) ? { concurrency: options.concurrency } : {},
           noCache: options.cache === false,
-          bail: options.bail
+          bail: options.bail,
+          ...options.cacheStrict ? { cacheStrict: true } : {},
+          ...cacheMaxAgeMs !== void 0 ? { cacheMaxAgeMs } : {}
         });
         if (options.only.length > 0 && result.evals.length === 0) {
           process.stderr.write("No evals matched the selector.\n");
@@ -6754,6 +7280,15 @@ function createProgram() {
         });
         writeReport(text2, options.output);
         process.exitCode = exitCodeFor2(result);
+        const missed = cacheMissRows2(result);
+        if (missed.length > 0) {
+          process.stderr.write(
+            `--cache-strict: ${missed.length} row(s) have no cache entry:
+${missed.map((m) => `  - ${m}`).join("\n")}
+`
+          );
+          process.exitCode = CACHE_STRICT_EXIT2;
+        }
       } catch (err) {
         const verbose = globals.verbose === true;
         if (err instanceof ConfigValidationError2) {
@@ -6803,11 +7338,12 @@ function createProgram() {
   };
   const verboseOf = (command) => command.optsWithGlobals().verbose === true;
   const FAIL_ON_FAILURES = "Exit with the platform's verdict on the run: 1 on a failed or broken result (muted ones do not count), on an expected case that never ran, or when there is no verdict at all";
-  runCommand.command("start").description("Open a platform run (or join one already carrying the key) and print its id").option("--key <externalKey>", "The key several processes share; generated when absent").option("--json", "Print one machine-readable line instead of prose", false).action(async (options, command) => {
+  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("--name <text>", "What to call the run in the list (default: the folder name, the time and where it ran; PLUNE_RUN_TITLE sets it too)").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 } : {},
+        ...options.name !== void 0 ? { name: options.name } : {},
         json: options.json
       });
     } catch (err) {
@@ -6831,12 +7367,13 @@ function createProgram() {
   );
   runCommand.command("exec").argument("<command...>", "The command to run inside the run, after `--`").description(
     "Open a run, run a command inside it, close the run \u2014 whatever the command returns"
-  ).option("--key <externalKey>", "The key several processes share; generated when absent").option("--fail-on-failures", `${FAIL_ON_FAILURES}; the command's own exit code when no result reached the run`, false).action(async (argv, options, command) => {
+  ).option("--key <externalKey>", "The key several processes share; generated when absent").option("--name <text>", "What to call the run in the list (default: the folder name, the time and where it ran; PLUNE_RUN_TITLE sets it too)").option("--fail-on-failures", `${FAIL_ON_FAILURES}; the command's own exit code when no result reached the run`, false).action(async (argv, options, command) => {
     try {
       const { handleRunExec: handleRunExec2 } = await Promise.resolve().then(() => (init_run_lifecycle(), run_lifecycle_exports));
       process.exitCode = await handleRunExec2({
         argv,
         ...options.key !== void 0 ? { key: options.key } : {},
+        ...options.name !== void 0 ? { name: options.name } : {},
         ...options.failOnFailures ? { failOnFailures: true } : {}
       });
     } catch (err) {
@@ -6888,7 +7425,7 @@ function createProgram() {
       await failRunCommand(err, verboseOf(command));
     }
   });
-  runCommand.command("import").argument("<file>", "A JUnit XML or Playwright JSON report, or an Allure allure-results folder").description("Turn a report another runner wrote into a run in Plune \u2014 no provider key needed").option("--format <fmt>", "junit | playwright-json | allure; detected from the file (a folder is allure) when omitted").option("--key <externalKey>", "The key several jobs share so their reports land in one run").option("--create", "Offer tests nothing matched to the review queue", false).option(
+  runCommand.command("import").argument("<file>", "A JUnit XML or Playwright JSON report, or an Allure allure-results folder").description("Turn a report another runner wrote into a run in Plune \u2014 no provider key needed").option("--format <fmt>", "junit | playwright-json | allure; detected from the file (a folder is allure) when omitted").option("--key <externalKey>", "The key several jobs share so their reports land in one run").option("--name <text>", "What to call the run in the list (default: the folder name, the time and where it ran; PLUNE_RUN_TITLE sets it too)").option("--create", "Offer tests nothing matched to the review queue", false).option(
     "--fail-on-missing-attachments",
     "Exit 1 when a file the report names ([[ATTACHMENT|path]] in JUnit, a source in allure-results) is not there; the results are sent either way",
     false
@@ -6930,6 +7467,7 @@ function createProgram() {
           file,
           ...format !== void 0 ? { format } : {},
           ...options.key !== void 0 ? { key: options.key } : {},
+          ...options.name !== void 0 ? { name: options.name } : {},
           ...options.create ? { create: true } : {},
           ...options.uploadConcurrency !== void 0 ? { uploadConcurrency: options.uploadConcurrency } : {},
           ...options.timeout !== void 0 ? { timeoutSec: options.timeout } : {},
@@ -6953,7 +7491,7 @@ function createProgram() {
       Promise.resolve().then(() => (init_report(), report_exports)),
       Promise.resolve().then(() => (init_reporters(), reporters_exports))
     ]);
-    const cwd = globals.config !== void 0 ? (0, import_node_path5.dirname)((0, import_node_path5.resolve)(globals.config)) : process.cwd();
+    const cwd = globals.config !== void 0 ? (0, import_node_path6.dirname)((0, import_node_path6.resolve)(globals.config)) : process.cwd();
     try {
       const result = handleReport2({ cwd });
       const text2 = renderReport2(result, toFormat(options.format), {
@@ -7050,7 +7588,7 @@ function createProgram() {
     const globals = command.optsWithGlobals();
     const verbose = globals.verbose === true;
     const { handleSync: handleSync2, reportSyncFailure: reportSyncFailure2 } = await Promise.resolve().then(() => (init_sync(), sync_exports));
-    const cwd = globals.config !== void 0 ? (0, import_node_path5.dirname)((0, import_node_path5.resolve)(globals.config)) : process.cwd();
+    const cwd = globals.config !== void 0 ? (0, import_node_path6.dirname)((0, import_node_path6.resolve)(globals.config)) : process.cwd();
     try {
       const { id, url, gate } = await handleSync2({
         cwd,
@@ -7139,7 +7677,7 @@ function createProgram() {
       failUnexpected(err, verbose);
     }
   });
-  const requirementsCommand = program.command("requirements").description("Requirements on the platform \u2014 import them from a Markdown file");
+  const requirementsCommand = program.command("requirements").description("Requirements on the platform \u2014 import them, or their links to tests, from a Markdown file");
   requirementsCommand.command("import").argument("<file>", "A Markdown file (UTF-8, at most 1 MiB)").description(
     "Import requirements from a Markdown file. With no mapping flags it lists the tables and sections found; with them it is a dry run until --yes"
   ).option(
@@ -7166,6 +7704,30 @@ function createProgram() {
       failUnexpected(err, verbose);
     }
   });
+  requirementsCommand.command("links").argument("<file>", "A Markdown file with a traceability matrix (UTF-8, at most 1 MiB)").description(
+    "Import a traceability matrix (requirement key -> test) as links. With no flags it lists the tables found; with them it is a dry run until --yes"
+  ).option("--table <n>", "The table with the matrix (its number from the list)").option("--requirement-column <header>", "The column holding the requirement keys").option("--test-column <header>", "The column holding the tests: an exact case title or a source path, one per line").option("--separator <text>", 'Splits a requirement cell into several keys, 1 to 3 characters (default ",")').option("--project <id>", "The project (default: PLUNE_PROJECT, else the only project of the account)").option("--yes", "Write it. Without it the import is a dry run", false).option("--json", "Print the platform\u2019s answer as JSON", false).option("--fail-on-unmatched", "Exit 1 when any requirement or test of the matrix matched nothing", false).action(async (file, options, command) => {
+    const verbose = command.optsWithGlobals().verbose === true;
+    const { handleRequirementsLinks: handleRequirementsLinks2, formatLinksDiscover: formatLinksDiscover2, formatLinks: formatLinks2 } = await Promise.resolve().then(() => (init_requirements_links(), requirements_links_exports));
+    const { reportRequirementsImportFailure: reportRequirementsImportFailure2 } = await Promise.resolve().then(() => (init_requirements_import(), requirements_import_exports));
+    try {
+      const res = await handleRequirementsLinks2({ file, ...options });
+      if (options.json === true) {
+        process.stdout.write(JSON.stringify(res.step === "discover" ? res.result : res.report, null, 2) + "\n");
+      } else {
+        process.stdout.write(res.step === "discover" ? formatLinksDiscover2(file, res.result) : formatLinks2(res.report));
+      }
+      if (options.failOnUnmatched === true && res.step === "links" && res.report.summary.unmatched > 0) process.exitCode = 1;
+    } catch (err) {
+      const code = reportRequirementsImportFailure2(err, (s) => process.stderr.write(s));
+      if (code !== null) {
+        maybeStack(err, verbose);
+        process.exitCode = code;
+        return;
+      }
+      failUnexpected(err, verbose);
+    }
+  });
   const planCommand = program.command("plan").description("Test plans on the platform \u2014 what a plan collects, as something a runner can take");
   planCommand.command("grep").argument("<id>", "The plan").description(
     "Print the plan's cases as one --grep pattern for the runner (GET /v1/plans/:id/cases)"
@@ -7190,6 +7752,57 @@ function createProgram() {
       failUnexpected(err, verbose);
     }
   });
+  program.command("verify").description(
+    "Compare the project's automated cases with the Playwright tests in the code, read-only \u2014 both sides of the drift, nothing written"
+  ).option("--from <file>", "A saved `playwright test --list --reporter=json` document instead of running Playwright").option("--playwright-config <path>", "Passed to `playwright test --config`").option("--json", "Print the report as JSON", false).option("--fail-on-drift", "Exit 1 when either side has something the other lacks", false).action(
+    async (options, command) => {
+      const verbose = verboseOf(command);
+      const { handleVerify: handleVerify2, formatVerify: formatVerify2 } = await Promise.resolve().then(() => (init_verify(), verify_exports));
+      const { reportCasesFailure: reportCasesFailure2 } = await Promise.resolve().then(() => (init_cases(), cases_exports));
+      try {
+        const report = await handleVerify2({
+          ...options.from === void 0 ? {} : { from: options.from },
+          ...options.playwrightConfig === void 0 ? {} : { playwrightConfig: options.playwrightConfig }
+        });
+        process.stdout.write(options.json ? JSON.stringify(report, null, 2) + "\n" : formatVerify2(report));
+        if (options.failOnDrift && report.onlyInPlatform.length + report.onlyInCode.length > 0) process.exitCode = 1;
+      } catch (err) {
+        const code = reportCasesFailure2(err, (s) => process.stderr.write(s));
+        if (code !== null) {
+          maybeStack(err, verbose);
+          process.exitCode = code;
+          return;
+        }
+        failUnexpected(err, verbose);
+      }
+    }
+  );
+  program.command("ids").description(
+    "Write the Plune case id of each Playwright test that names none into plune/ids.json (dry run unless --write); test sources are not touched"
+  ).option("--write", "Write the file; without it only shows what would be written", false).option("--file <path>", "The mapfile", "plune/ids.json").option("--from <file>", "A saved `playwright test --list --reporter=json` document instead of running Playwright").option("--playwright-config <path>", "Passed to `playwright test --config`").option("--json", "Print the report as JSON", false).action(
+    async (options, command) => {
+      const verbose = verboseOf(command);
+      const { handleIds: handleIds2, formatIds: formatIds2 } = await Promise.resolve().then(() => (init_ids(), ids_exports));
+      const { reportCasesFailure: reportCasesFailure2 } = await Promise.resolve().then(() => (init_cases(), cases_exports));
+      try {
+        const report = await handleIds2({
+          write: options.write,
+          file: options.file,
+          ...options.from === void 0 ? {} : { from: options.from },
+          ...options.playwrightConfig === void 0 ? {} : { playwrightConfig: options.playwrightConfig }
+        });
+        process.stdout.write(options.json ? JSON.stringify(report, null, 2) + "\n" : formatIds2(report, options.write));
+      } catch (err) {
+        const code = reportCasesFailure2(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(" ")}
 `);
@@ -7201,7 +7814,7 @@ function isMainModule() {
   const entry = process.argv[1];
   if (entry === void 0) return false;
   try {
-    return (0, import_node_fs8.realpathSync)(entry) === (0, import_node_fs8.realpathSync)((0, import_node_url.fileURLToPath)(importMetaUrl));
+    return (0, import_node_fs10.realpathSync)(entry) === (0, import_node_fs10.realpathSync)((0, import_node_url.fileURLToPath)(importMetaUrl));
   } catch {
     return false;
   }