niceeval 0.6.1 → 0.7.0

package/src/results/select.ts

@@ -1,8 +1,8 @@
-// 快照 Selection 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「身份键与去重」)。
+// 快照 Scope 与 attempt 去重(定稿见 docs/feature/results/library.md「选择快照」「官方现刻水位」「身份键与去重」)。
 //
-// 选择器只有一个(latest),长在集合上;它不是 DSL,只是最常用的那次筛选。
-// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Selection 走 ——
-// 渲染与否在消费方(message 是渲染好的英文句子),但缺口不静默。
+// 选择器长在集合上(results.latest() / results.current()),不是 DSL,只是最常用的两种口径。
+// 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
+// 渲染与否在消费方(message 是渲染好的英文句子,以下一步收尾),但缺口不静默。
 
 import type {
   AttemptHandle,
@@ -10,22 +10,23 @@ import type {
   Eval,
   Experiment,
   Results,
-  Selection,
-  SelectionWarning,
+  Scope,
+  ScopeWarning,
   Snapshot,
 } from "./types.ts";
+import type { ExperimentRunInfo, JsonValue } from "../types.ts";
 import { evalPrefixPredicate } from "../shared/aggregate.ts";
 
 /** Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。 */
 export function selectLatest(
   experiments: Experiment[],
   opts?: { experiments?: string | string[] },
-): Selection {
+): Scope {
   const selected = filterExperiments(experiments, opts?.experiments);
   const snapshots = selected.map((exp) => exp.latest);
-  const warnings: SelectionWarning[] = [];
+  const warnings: ScopeWarning[] = [];
 
-  // stale 的基准:Selection 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
+  // stale 的基准:Scope 中最新的落盘(无阈值,如实触发;要阈值消费方按字段自比)。
   let latestStartedAt = "";
   for (const snapshot of snapshots) {
     if (snapshot.startedAt > latestStartedAt) latestStartedAt = snapshot.startedAt;
@@ -44,6 +45,7 @@ export function selectLatest(
         covered,
         total,
         message: `snapshot covers ${covered} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
     if (snapshot.startedAt < latestStartedAt) {
@@ -52,7 +54,8 @@ export function selectLatest(
         experimentId: exp.id,
         startedAt: snapshot.startedAt,
         latestStartedAt,
-        message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this selection by ${humanizeGap(snapshot.startedAt, latestStartedAt)}`,
+        message: `snapshot "${exp.id}" (${snapshot.startedAt}) predates the latest run in this scope by ${humanizeGap(snapshot.startedAt, latestStartedAt)}; re-run \`niceeval exp ${exp.id}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
     if (!snapshot.completedAt) {
@@ -61,46 +64,101 @@ export function selectLatest(
         experimentId: exp.id,
         startedAt: snapshot.startedAt,
         dir: snapshot.dir,
-        message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; results may be incomplete`,
+        message: `snapshot "${exp.id}" (${snapshot.startedAt}) has no completedAt — the run was interrupted; re-run \`niceeval exp ${exp.id}\` for a complete snapshot`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
   }
-  return makeSelection(snapshots, warnings);
+  return makeScope("latest-snapshots", snapshots, warnings);
 }
 
 /** selectCurrentResults 的范围输入:experiment id 前缀与 eval id 前缀,都可缺省。 */
 export interface ResultScope {
   /** experiment id 前缀(--experiment),分段匹配语义同 filterExperiments。 */
-  experiment?: string;
-  /** eval id 前缀(位置参数),收窄 Selection 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
+  experiment?: string | string[];
+  /** eval id 前缀(位置参数),收窄 Scope 覆盖的 eval;覆盖警告分母同步收窄到范围内。 */
   patterns?: string[];
 }
 
+// ───────────────────────── 可比性配置 ─────────────────────────
+
+/**
+ * current() 跨快照拼接的可比性前提所比较的字段集(docs/feature/results/library.md
+ * 「官方现刻水位」):会改变单题被测行为或判定的字段。runs / earlyExit / maxConcurrency /
+ * selectedEvalIds / evalFilterFingerprint / description 是编排与选题字段,不参与比较。
+ */
+export interface ComparabilityConfig {
+  agent: string;
+  model?: string;
+  reasoningEffort?: string;
+  flags?: Record<string, JsonValue>;
+  budget?: number;
+  timeoutMs?: number;
+  sandbox?: ExperimentRunInfo["sandbox"];
+}
+
+/** 一个快照的可比性配置投影;pairsByFlag 与 experimentListData 复用同一字段集。 */
+export function comparabilityConfigOf(snapshot: Snapshot): ComparabilityConfig {
+  const info = snapshot.experiment;
+  return {
+    agent: snapshot.agent,
+    ...(snapshot.model !== undefined ? { model: snapshot.model } : {}),
+    ...(info?.reasoningEffort !== undefined ? { reasoningEffort: info.reasoningEffort } : {}),
+    ...(info?.flags !== undefined ? { flags: info.flags } : {}),
+    ...(info?.budget !== undefined ? { budget: info.budget } : {}),
+    ...(info?.timeoutMs !== undefined ? { timeoutMs: info.timeoutMs } : {}),
+    ...(info?.sandbox !== undefined ? { sandbox: info.sandbox } : {}),
+  };
+}
+
+/** 可序列化值的深相等(对象键序无关;undefined 字段与缺席字段等价)。 */
+export function deepEqualJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, i) => deepEqualJson(item, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+    const keysA = Object.keys(a).filter((k) => (a as Record<string, unknown>)[k] !== undefined);
+    const keysB = Object.keys(b).filter((k) => (b as Record<string, unknown>)[k] !== undefined);
+    if (keysA.length !== keysB.length) return false;
+    return keysA.every((k) =>
+      deepEqualJson((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]),
+    );
+  }
+  return false;
+}
+
 /**
- * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取时间上最新的那份
- * 判定,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval 前缀的局部重跑会产出
- * 残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的全部历史快照上逐 eval
- * 向更早的 run 补齐,再把合成好的 Selection 交给宿主注入报告槽——内置默认报告与 --report 吃
- * 同一份。
+ * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
+ * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
+ * 前缀的局部重跑会产出残缺快照;现刻水位承诺「不会因为一次局部重跑变残缺」,所以在实验的
+ * 历史快照上逐 eval 向更早的 run 补齐,再把合成好的 Scope 交给宿主注入报告槽。
+ *
+ * **可比性前提**:每个 experiment 以最新快照的可比性配置(agent / model / reasoningEffort /
+ * flags / budget / timeoutMs / sandbox)为基准,只有配置与基准深相等的历史快照才参与补齐;
+ * 改过配置后只补跑部分 eval 时,旧配置快照覆盖的其余题不冒充新配置的水位,按 partial-coverage
+ * 如实告警。这保证 current() 产出的每个 experiment 只对应一套配置。
  *
  * 同一 eval 的全部 attempts 必须整批取自包含它的最新快照,不把历史快照的 attempts 平铺后
  * 按 eval 聚合——否则会把不同运行的重试混成一次虚构运行。合成快照的 dir/元数据只服务报告
  * 分组与来源展示,证据身份一律来自 attempt 自己的 ref。
- * 警告随 Selection 重算:partial-coverage 的分母 = 已知并集 ∩ 范围(范围收窄时分母同步收窄,
- * 不让范围外的缺口刷屏);stale / unfinished 与 results.latest() 同口径。
  */
-export function selectCurrentResults(results: Results, scope: ResultScope = {}): Selection {
+export function selectCurrentResults(results: Results, scope: ResultScope = {}): Scope {
   const match =
     scope.patterns && scope.patterns.length > 0 ? evalPrefixPredicate(scope.patterns) : () => true;
   const experiments = filterExperiments(results.experiments, scope.experiment);
 
   const snapshots: Snapshot[] = [];
-  const warnings: SelectionWarning[] = [];
+  const warnings: ScopeWarning[] = [];
 
   for (const exp of experiments) {
+    // 可比性基准 = 该实验最新快照的可比性配置;不一致的旧快照整份跳过,不贡献 attempt。
+    const baseline = comparabilityConfigOf(exp.latest);
     // 逐题取最新:快照按最新在前,首个出现即最新判定
     const taken = new Map<string, { ev: Eval; snapshot: Snapshot }>();
     for (const snapshot of exp.snapshots) {
+      if (!deepEqualJson(comparabilityConfigOf(snapshot), baseline)) continue;
       for (const ev of snapshot.evals) {
         if (!match(ev.id) || taken.has(ev.id)) continue;
         taken.set(ev.id, { ev, snapshot });
@@ -124,6 +182,8 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
       startedAt,
       agent: base.agent,
       ...(base.model !== undefined ? { model: base.model } : {}),
+      ...(base.experiment !== undefined ? { experiment: base.experiment } : {}),
+      ...(base.name !== undefined ? { name: base.name } : {}),
       producer: base.producer,
       schemaVersion: base.schemaVersion,
       evals,
@@ -133,8 +193,8 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
       ...(base.knownEvalIds ? { knownEvalIds: [...base.knownEvalIds] } : {}),
     });
 
-    // 残缺检测:跨快照补齐后仍缺,只可能是历史上见过(或 knownEvalIds 声明过)
-    // 却从未在可读落盘里出现的题 —— 分母收窄到范围内,不让范围外的缺口刷屏。
+    // 残缺检测:跨快照补齐后仍缺,来自「历史上见过却从未在可比配置的可读落盘里出现」的题
+    // (含改配置后未补跑的题)—— 分母收窄到范围内,不让范围外的缺口刷屏。
     const total = exp.evalIds.filter(match).length;
     if (evals.length < total) {
       warnings.push({
@@ -143,6 +203,7 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
         covered: evals.length,
         total,
         message: `verdicts cover ${evals.length} of ${total} evals seen in history; re-run \`niceeval exp ${exp.id}\` for a full snapshot`,
+        command: `niceeval exp ${exp.id}`,
       });
     }
   }
@@ -158,7 +219,8 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
         experimentId: snapshot.experimentId,
         startedAt: snapshot.startedAt,
         latestStartedAt,
-        message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, before the latest run in this selection (${latestStartedAt})`,
+        message: `verdicts for "${snapshot.experimentId}" were produced at ${snapshot.startedAt}, ${humanizeGap(snapshot.startedAt, latestStartedAt)} before the latest run in this scope; re-run \`niceeval exp ${snapshot.experimentId}\` to align, or ignore if evals, agent and model are unchanged between the runs`,
+        command: `niceeval exp ${snapshot.experimentId}`,
       });
     }
     if (snapshot.completedAt === undefined) {
@@ -167,37 +229,45 @@ export function selectCurrentResults(results: Results, scope: ResultScope = {}):
         experimentId: snapshot.experimentId,
         startedAt: snapshot.startedAt,
         dir: snapshot.dir,
-        message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete`,
+        message: `snapshot "${snapshot.experimentId}" (${snapshot.startedAt}) is unfinished (the process was interrupted); completed attempts are read as-is, but the set may be incomplete — re-run \`niceeval exp ${snapshot.experimentId}\` for a complete snapshot`,
+        command: `niceeval exp ${snapshot.experimentId}`,
       });
     }
   }
 
-  return makeSelection(snapshots, warnings);
+  return makeScope("current-evals", snapshots, warnings);
 }
 
 /**
- * Selection 构造:filter 只删不换 —— 快照删减,warnings 修剪规则是
- * 「experimentId 不在幸存快照中的丢弃,非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
+ * Scope 构造:attempts 按口径物化(快照 attempts 的平铺);filter 只删不换 —— 快照删减,
+ * attempts 随之同步修剪,warnings 修剪规则是「experimentId 不在幸存快照中的丢弃,
+ * 非实验作用域的保留」(为将来非 per-experiment 的 kind 留位置)。
  */
-export function makeSelection(snapshots: Snapshot[], warnings: SelectionWarning[]): Selection {
+export function makeScope(
+  mode: Scope["mode"],
+  snapshots: Snapshot[],
+  warnings: ScopeWarning[],
+): Scope {
   return {
+    mode,
     snapshots,
+    attempts: snapshots.flatMap((s) => s.attempts),
     warnings,
-    filter(predicate: (snapshot: Snapshot) => boolean): Selection {
+    filter(predicate: (snapshot: Snapshot) => boolean): Scope {
       const kept = snapshots.filter(predicate);
       const survivors = new Set(kept.map((s) => s.experimentId));
       const keptWarnings = warnings.filter((w) => {
         const scope = (w as { experimentId?: unknown }).experimentId;
         return typeof scope !== "string" || survivors.has(scope);
       });
-      return makeSelection(kept, keptWarnings);
+      return makeScope(mode, kept, keptWarnings);
     },
   };
 }
 
 /**
  * 跨快照聚合前的身份键去重:(experimentId, evalId, attempt, startedAt)。
- * --resume 会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
+ * 携带合入会把上一轮已通过的结果原样合入新快照,同一 attempt 因此存在于多份落盘;
  * 重复时保留最新快照里的那份(内容相同,取新快照的副本让 ref 落在最新落盘上;
  * 位置取首次出现处,顺序稳定)。startedAt 缺失时宁可不去重也不误删,记入 warnings。
  */

package/src/results/truncate.ts

@@ -0,0 +1,90 @@
+// 落盘大值截断(见 docs/feature/results/architecture.md「大值截断」)。
+// 运行时全量,落盘截断:落点唯一在 snap.writeAttempt(writer.ts)——不在 adapter、不在 OTLP
+// 解析、不在事件归一化里做。适用范围:events.json 的事件字段与 trace.json 的 span 属性里的
+// 任意字符串值。没有 flag、没有配置项;截断永远不影响判决(落盘是证据,不是评分输入)。
+
+import type { StreamEvent, TraceSpan, Truncation } from "../types.ts";
+
+/** 每个字符串值的落盘上限(UTF-8 字节)。 */
+export const ARTIFACT_VALUE_MAX_BYTES = 256 * 1024;
+
+const encoder = new TextEncoder();
+
+/** 截断到 maxBytes(按 UTF-8 字符边界回退,不切断多字节字符),末尾追加人可读 marker。 */
+function truncateString(value: string, originalBytes: number): string {
+  // 按字节预算切:先按「字节数 ≥ 字符数」粗切,再逐步回退到不超预算的字符边界。
+  let sliceLen = Math.min(value.length, ARTIFACT_VALUE_MAX_BYTES);
+  let head = value.slice(0, sliceLen);
+  while (encoder.encode(head).length > ARTIFACT_VALUE_MAX_BYTES && sliceLen > 0) {
+    // 超出量 ÷ 4(UTF-8 最长 4 字节)是安全的最小回退步长;循环兜底处理边界。
+    sliceLen -= Math.max(1, Math.ceil((encoder.encode(head).length - ARTIFACT_VALUE_MAX_BYTES) / 4));
+    head = value.slice(0, sliceLen);
+  }
+  const kept = encoder.encode(head).length;
+  return `${head}\n[niceeval] truncated ${originalBytes} → ${kept} bytes`;
+}
+
+/**
+ * 深度遍历一个 JSON 值,截断其中超限的字符串;返回(可能新建的)值与收集到的截断记录。
+ * `path` 用点分段(数组下标同样入段),事件里从字段名起、span 属性里从 attribute key 起。
+ */
+function truncateJsonValue(value: unknown, path: string, out: Truncation[]): unknown {
+  if (typeof value === "string") {
+    const bytes = encoder.encode(value).length;
+    if (bytes <= ARTIFACT_VALUE_MAX_BYTES) return value;
+    out.push({ path, originalBytes: bytes });
+    return truncateString(value, bytes);
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const next = value.map((v, i) => {
+      const r = truncateJsonValue(v, `${path}.${i}`, out);
+      if (r !== v) changed = true;
+      return r;
+    });
+    return changed ? next : value;
+  }
+  if (value !== null && typeof value === "object") {
+    let changed = false;
+    const next: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) {
+      const r = truncateJsonValue(v, path ? `${path}.${k}` : k, out);
+      if (r !== v) changed = true;
+      next[k] = r;
+    }
+    return changed ? next : value;
+  }
+  return value;
+}
+
+/** events.json 落盘前的截断:逐事件处理全部字符串字段,超限的加结构化 `truncated` 标记。 */
+export function truncateEvents(events: readonly StreamEvent[]): StreamEvent[] {
+  return events.map((event) => {
+    const out: Truncation[] = [];
+    const next: Record<string, unknown> = {};
+    let changed = false;
+    for (const [k, v] of Object.entries(event)) {
+      if (k === "type" || k === "truncated") {
+        next[k] = v;
+        continue;
+      }
+      const r = truncateJsonValue(v, k, out);
+      if (r !== v) changed = true;
+      next[k] = r;
+    }
+    if (!changed) return event;
+    return { ...next, truncated: [...(event.truncated ?? []), ...out] } as StreamEvent;
+  });
+}
+
+/** trace.json 落盘前的截断:span 属性里的任意字符串值(name 一并覆盖——可携带动态内容)。 */
+export function truncateSpans(spans: readonly TraceSpan[]): TraceSpan[] {
+  return spans.map((span) => {
+    const out: Truncation[] = [];
+    const attributes = span.attributes
+      ? (truncateJsonValue(span.attributes, "", out) as TraceSpan["attributes"])
+      : span.attributes;
+    if (out.length === 0) return span;
+    return { ...span, attributes, truncated: [...(span.truncated ?? []), ...out] };
+  });
+}

package/src/results/types.ts

@@ -44,6 +44,11 @@ export interface SnapshotMeta {
   completedAt?: string;
   /** 写入时刻该实验已知的 eval 并集 —— 残缺检测的分母随数据走(copySnapshots 自动补记,writer 可声明)。 */
   knownEvalIds?: string[];
+  /**
+   * 发布拷贝的自描述标记:copySnapshots 补记,消毒函数 → "applied"、redact: false → "none";
+   * 本地事实根没有此字段。只声明流程,不证明无秘密;view --out 据此分级防呆。
+   */
+  publish?: { redaction: "applied" | "none" };
   /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
   name?: LocalizedText;
 }
@@ -125,6 +130,8 @@ export interface Snapshot {
   dir: string;
   /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
   knownEvalIds?: string[];
+  /** 发布拷贝的自描述标记(见 SnapshotMeta.publish);本地事实根没有此字段。 */
+  publish?: { redaction: "applied" | "none" };
 }
 
 /** 一个实验的全部历史:同一 experiment id 的历次快照归在一起。 */
@@ -164,33 +171,49 @@ export interface Results {
   experiments: Experiment[];
   skipped: SkippedDir[];
   /**
-   * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
+   * 每个实验取最新一次快照,返回 Scope(快照与挑选警告绑在一起走)。
    * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
    */
-  latest(opts?: { experiments?: string | string[] }): Selection;
+  latest(opts?: { experiments?: string | string[] }): Scope;
+  /**
+   * 官方现刻水位:每个 experiment × eval 取「包含该 eval 的最新快照」里的全部 attempt,
+   * 跨历史拼出当前判定水位。可比性前提:每个 experiment 以最新快照的可比性配置
+   * (agent / model / reasoningEffort / flags / budget / timeoutMs / sandbox)为基准,
+   * 配置不一致的旧快照不贡献 attempt,缺口走 partial-coverage
+   * (见 docs/feature/results/library.md「官方现刻水位」)。
+   */
+  current(opts?: { experiments?: string | string[] }): Scope;
 }
 
 /**
- * Selection:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
- * 下游(Reports 计算函数、copySnapshots)收 `Selection | Snapshot[]`;
- * 手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
+ * Scope(范围):选出的快照 + 口径 + 已按口径物化的 attempt 全集 + 挑选警告。
+ * 渲染与否在消费方,但缺口永远被算出来。下游(Reports 计算函数、copySnapshots)收
+ * `Scope | readonly Snapshot[]`;手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
  */
-export interface Selection {
+export interface Scope {
+  /** 这份 Scope 的口径,字面写在数据上。 */
+  mode: "latest-snapshots" | "current-evals";
   snapshots: Snapshot[];
-  warnings: SelectionWarning[];
   /**
-   * 只删不换:返回新 Selection,快照删减,warnings 按规则修剪 ——
-   * experimentId 不在幸存快照中的丢弃,非实验作用域的保留。
+   * 按口径物化的 attempt 全集:消费 attempts 就自动正确,不需要自己 flatten snapshots,
+   * 也就不可能算错口径。官方计算函数同样只消费它。
+   */
+  attempts: AttemptHandle[];
+  warnings: ScopeWarning[];
+  /**
+   * 只删不换:返回新 Scope,快照删减,attempts 与 warnings 随之同步修剪 ——
+   * experimentId 不在幸存快照中的警告丢弃,非实验作用域的警告保留。
    * 「换成上一个完整快照」这类替换式重挑不给方法,回 exp.snapshots 自己挑。
    */
-  filter(predicate: (snapshot: Snapshot) => boolean): Selection;
+  filter(predicate: (snapshot: Snapshot) => boolean): Scope;
 }
 
 /**
- * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;
- * kind 是契约的一部分,全集与触发条件见 docs/feature/results/library.md「警告 kind 全集」。
+ * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;能用一条命令直接推进的
+ * kind 同时带 `command`(已替换真实 id,复制即跑)。kind 是契约的一部分,全集与触发条件见
+ * docs/feature/results/library.md「警告 kind 全集」。
  */
-export type SelectionWarning =
+export type ScopeWarning =
   | {
       /** 选中快照的覆盖 < 该实验已知 eval 并集(本地历史 ∪ knownEvalIds)。 */
       kind: "partial-coverage";
@@ -198,14 +221,18 @@ export type SelectionWarning =
       covered: number;
       total: number;
       message: string;
+      /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+      command: string;
     }
   | {
-      /** 该实验选中的快照早于 Selection 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+      /** 该实验选中的快照早于 Scope 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
       kind: "stale-snapshot";
       experimentId: string;
       startedAt: string;
       latestStartedAt: string;
       message: string;
+      /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+      command: string;
     }
   | {
       /** 选中快照缺 completedAt(进程中断,未收尾);已落盘 attempt 照常读出,警告提示集合可能不完整。 */
@@ -215,6 +242,8 @@ export type SelectionWarning =
       /** 该快照目录的绝对路径。 */
       dir: string;
       message: string;
+      /** 一条可复制即跑的推进命令:`niceeval exp <experimentId>`。 */
+      command: string;
     };
 
 /** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */

package/src/results/writer.ts

@@ -9,16 +9,28 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { AgentSetupManifest, EvalResult, ExperimentRunInfo, LocalizedText } from "../types.ts";
-import type { DiffData, O11ySummary, SourceArtifact, StreamEvent, TraceSpan } from "../types.ts";
+import type { DiffArtifact, O11ySummary, SourceArtifact, StreamEvent, TraceSpan } from "../types.ts";
 import { RESULTS_FORMAT, RESULTS_SCHEMA_VERSION } from "../types.ts";
 import { RESULT_FILE, SNAPSHOT_FILE, artifactFileOf, attemptDirOf, experimentDirOf } from "./format.ts";
 import { encodeAttemptLocator } from "./locator.ts";
 import { hashEvalSource, normalizeEvalSource } from "./source-hash.ts";
+import { truncateEvents, truncateSpans } from "./truncate.ts";
 import type { Producer, SnapshotMeta } from "./types.ts";
 
 export interface ResultsWriterOptions {
   /** 谁在写这份结果:niceeval 自己,或第三方 harness(name 如实写,别冒充 "niceeval")。 */
   producer: Producer;
+  /**
+   * 本次 invocation 的快照身份锚点(ISO 时间戳,即 runner 的 `RunShape.snapshotStartedAt`)。
+   * `writeAttemptFor()` 的隐式 snapshot 声明统一用它做 `startedAt`,不再按「该 experiment
+   * 第一条落盘 result 的 attempt startedAt」猜 —— 那个锚点依赖并发完成顺序,不确定;
+   * 同一 writer 处理多个 experiment 时也共享这同一个值(locator 身份还含 experimentId,
+   * 不会碰撞)。省略时退回旧行为:每次隐式声明按 `result.startedAt ?? now()` 各自取锚,
+   * 供未提供该值的直调场景使用(测试、结果转换脚本、第三方 harness 直接调
+   * `createResultsWriter()` 而不经过 niceeval 自己的 runner)。显式调用 `writer.snapshot()`
+   * 声明快照的调用方不受这个选项影响,必须自己传 `SnapshotDeclaration.startedAt`。
+   */
+  snapshotStartedAt?: string;
 }
 
 /** 快照级声明:一个 experiment 声明一次,这些字段不塞进每条 attempt。 */
@@ -70,7 +82,7 @@ export interface AttemptArtifacts {
   o11y?: O11ySummary;
   /** agent setup 的安装清单(沙箱型 coding agent 装了 Skill / plugin / MCP 才有)。 */
   agentSetup?: AgentSetupManifest;
-  diff?: DiffData;
+  diff?: DiffArtifact;
   sources?: SourceArtifact[];
 }
 
@@ -118,7 +130,7 @@ export function createResultsWriter(root: string, opts: ResultsWriterOptions): R
       producer: opts.producer,
       experimentId: decl.experimentId,
       // 运行配置不带 id:身份的家是顶层 experimentId,重复一份只会引出「以谁为准」。
-      ...(decl.experiment !== undefined ? { experiment: stripInfoId(decl.experiment) } : {}),
+      ...(decl.experiment !== undefined ? { experiment: (decl.experiment) } : {}),
       agent: decl.agent,
       ...(decl.model !== undefined ? { model: decl.model } : {}),
       startedAt: decl.startedAt,
@@ -172,8 +184,11 @@ export function createResultsWriter(root: string, opts: ResultsWriterOptions): R
       experimentId: result.experimentId,
       agent: result.agent,
       model: result.model,
-      // 快照 startedAt 以该实验首条落盘结果的 attempt 时刻为锚(首条 ≈ 实验开跑)。
-      startedAt: result.startedAt ?? new Date().toISOString(),
+      // 快照 startedAt 优先用 writer 级的 invocation 锚点(见 ResultsWriterOptions.snapshotStartedAt)——
+      // niceeval 自己的 runner 恒会提供,多个 experiment 共享同一个值。省略时(第三方直调
+      // createResultsWriter() 未传该选项)退回旧行为:以本次调用这个 result 自己的 attempt
+      // startedAt 为锚,首条落盘的 result 决定了这个 experiment 快照的身份锚点。
+      startedAt: opts.snapshotStartedAt ?? result.startedAt ?? new Date().toISOString(),
       experiment: result.experiment,
     });
 
@@ -288,9 +303,14 @@ async function writeAttemptFiles(
   const hasTrace = !!(artifacts?.trace && artifacts.trace.length);
 
   const writes: Promise<unknown>[] = [];
-  if (hasEvents) writes.push(writeFile(join(attemptDir, "events.json"), JSON.stringify(artifacts!.events), "utf-8"));
+  // 大值截断只发生在这里(序列化的那一刻):events 的事件字段与 trace 的 span 属性里的任意
+  // 字符串值按 ARTIFACT_VALUE_MAX_BYTES 截断并留结构化 truncated 标记;运行时(断言 / o11y
+  // 派生)看到的始终是完整值。sources 与 diff 不截断(见 docs/feature/results/architecture.md)。
+  if (hasEvents)
+    writes.push(writeFile(join(attemptDir, "events.json"), JSON.stringify(truncateEvents(artifacts!.events!)), "utf-8"));
   if (hasSources) writes.push(writeSourcesRef(snapDir, attemptDir, artifacts!.sources!, sourceStore));
-  if (hasTrace) writes.push(writeFile(join(attemptDir, "trace.json"), JSON.stringify(artifacts!.trace), "utf-8"));
+  if (hasTrace)
+    writes.push(writeFile(join(attemptDir, "trace.json"), JSON.stringify(truncateSpans(artifacts!.trace!)), "utf-8"));
   if (artifacts?.o11y) writes.push(writeFile(join(attemptDir, "o11y.json"), JSON.stringify(artifacts.o11y), "utf-8"));
   if (artifacts?.agentSetup) {
     writes.push(
@@ -303,6 +323,9 @@ async function writeAttemptFiles(
   // locator:caller(如第三方 harness 直接调 SnapshotWriter.writeAttempt)已经带了就尊重,
   // 否则按当前身份元组算一份 —— 这条路径只服务「非携带」的新写入,携带条目走
   // writeAttemptForImpl 的 artifactBase 分支,原样透传 result.locator,从不落到这里重算。
+  // niceeval 自己的 runner(src/runner/run.ts)在 fresh attempt 完成时已经把 locator 写进
+  // entry.locator(用的正是同一个 snapshot.startedAt),所以这条 encodeAttemptLocator 兜底
+  // 对 niceeval 自身运行永不触发,只在第三方 harness 未预先算好 locator 时才会走到。
   const locator =
     entry.locator ??
     encodeAttemptLocator({
@@ -365,12 +388,7 @@ async function createSnapshotDir(root: string, experimentId: string): Promise<st
   throw new Error(`Could not create a unique snapshot directory under "${parent}" after 5 attempts (${String(lastError)}).`);
 }
 
-/** 运行配置落盘前剥掉 id:experimentId 的家在 snapshot.json 顶层。 */
-function stripInfoId(info: ExperimentRunInfo): ExperimentRunInfo {
-  const { id, ...rest } = info;
-  void id;
-  return rest;
-}
+
 
 /** 快照目录名的时间戳段:Date#toISOString 把 : 与 . 换成 -(与 docs/feature/results/architecture.md 一致)。 */
 function safeTimestamp(d: Date): string {