niceeval 0.6.1 → 0.7.0

package/src/sandbox/resolve.ts

@@ -4,11 +4,13 @@
 // 省略时 resolveSandbox() 直接抛错,不猜环境、不兜底。
 // provider 名的行为分支只允许出现在 sandbox/ 内(见 docs/architecture.md)。
 
+import { createHash, randomUUID } from "node:crypto";
 import { Effect } from "effect";
-import type { CustomSandboxSpec, Sandbox, SandboxOption, SandboxRuntime } from "../types.ts";
+import type { CustomSandboxSpec, JsonValue, Sandbox, SandboxOption, SandboxRuntime, ScopedFeedback } from "../types.ts";
 import { registerSandbox, stopSandbox } from "./registry.ts";
 import { normalizeSandboxPaths } from "./paths.ts";
 import { t } from "../i18n/index.ts";
+import { reportActivity, reportDiagnostic } from "../runner/feedback/sink.ts";
 import { withProvisionRetry, type ProvisionSlot } from "./retry.ts";
 
 /** 归一化后的沙箱描述:确定的 provider + 各 provider 参数(只有对应 provider 用得上的会有值)。 */
@@ -50,6 +52,36 @@ export function sandboxRecommendedConcurrency(opt: SandboxOption | undefined): n
   }
 }
 
+/**
+ * ExperimentRunInfo.sandbox 的投影:provider 名 + 公开参数(镜像/快照/模板/runtime)+ 配置指纹。
+ * 参数只经这个投影落盘——token、凭据路径永不进来;defineSandbox 自定义 provider 未实现
+ * `publicConfig()` 时只落 provider 名(见 docs/feature/results/architecture.md)。
+ */
+export function sandboxRunInfo(
+  opt: SandboxOption | undefined,
+): { provider: string; params?: Record<string, JsonValue>; fingerprint?: string } | undefined {
+  if (!opt) return undefined;
+  const r = resolveSandbox(opt);
+  let params: Record<string, JsonValue> | undefined;
+  if (r.create) {
+    // 自定义 provider:只有显式实现了 publicConfig() 投影才落参数。
+    params = (opt as CustomSandboxSpec).publicConfig?.();
+  } else {
+    const p: Record<string, JsonValue> = {};
+    if (r.image !== undefined) p.image = r.image;
+    if (r.snapshotId !== undefined) p.snapshotId = r.snapshotId;
+    if (r.template !== undefined) p.template = r.template;
+    if (r.runtime !== undefined) p.runtime = r.runtime;
+    params = Object.keys(p).length > 0 ? p : undefined;
+  }
+  if (params === undefined) return { provider: r.provider };
+  const fingerprint = createHash("sha256")
+    .update(JSON.stringify({ provider: r.provider, params }))
+    .digest("hex")
+    .slice(0, 16);
+  return { provider: r.provider, params, fingerprint };
+}
+
 /** 报告 / 日志用的简短标签:provider 名,带上区分性的参数(镜像 / 快照 / 模板)。 */
 export function sandboxLabel(opt: SandboxOption | undefined): string {
   const r = resolveSandbox(opt);
@@ -61,59 +93,92 @@ export function sandboxLabel(opt: SandboxOption | undefined): string {
  * 按解析出的 provider + 参数创建沙箱,并把 stop() 注册为 Scope 回收动作。
  * 在 Effect.scoped / Effect.gen 里 yield* 即可;成功/失败/中断都保证 stop。
  */
+/** 没有 runner 绑定 feedback 时(测试直调等)的兜底:退回全局 sink,行为与旧接线一致。 */
+function fallbackFeedback(): ScopedFeedback {
+  return {
+    progress: (u) =>
+      reportActivity(u.current !== undefined && u.total !== undefined ? `${u.message} (${u.current}/${u.total})` : u.message),
+    diagnostic: (d) =>
+      reportDiagnostic({ key: d.dedupeKey ?? d.code, severity: d.level, message: d.message, data: d.data }),
+  };
+}
+
 export function createSandbox(opts: {
   sandbox?: SandboxOption;
   timeout?: number;
   runtime?: SandboxRuntime;
   /** 调用方并发槽位的临时归还/收回,传给 withProvisionRetry 在退避睡眠期间释放(见 retry.ts)。 */
   provisionSlot?: ProvisionSlot;
+  /** runner 绑定到 `sandbox.create` 阶段的反馈句柄;provider 的进度/诊断都走它。 */
+  feedback?: ScopedFeedback;
+  /**
+   * release 覆写(留存路径用):Scope 关闭时按调用方的 disposition 决定 stop 还是 suspend。
+   * 省略 = 恒 stopSandbox(默认销毁)。
+   */
+  release?: (sb: Sandbox) => Promise<void>;
 }) {
   const r = resolveSandbox(opts.sandbox, opts.runtime);
+  const feedback = opts.feedback ?? fallbackFeedback();
   return Effect.acquireRelease(
     Effect.promise<Sandbox>(async () => {
       // 起好就登记:让 cli 的兜底强清(二次 Ctrl+C / 看门狗超时)能直接停到它,不只靠下面的
       // release。即便本 fiber 创建后立刻被中断、release 还没来得及跑,登记表也已认得这个沙箱。
-      const sb = normalizeSandboxPaths(await createProvider(r, opts.timeout, opts.provisionSlot));
+      const sb = normalizeSandboxPaths(await createProvider(r, feedback, opts.timeout, opts.provisionSlot));
       registerSandbox(sb);
       return sb;
     }),
     // release:成功 / 失败 / 中断都跑。带超时 + 失败不静默(stopSandbox 内做),并把它移出登记表。
-    (sb) => Effect.promise(() => stopSandbox(sb)),
+    (sb) => Effect.promise(() => (opts.release ? opts.release(sb) : stopSandbox(sb))),
   );
 }
 
-async function createProvider(r: ResolvedSandbox, timeout?: number, provisionSlot?: ProvisionSlot): Promise<Sandbox> {
-  // 自定义 provider(defineSandbox):不认 provider 名,直接调用用户给的 create()。
-  if (r.create) return r.create({ timeout, runtime: r.runtime });
+async function createProvider(
+  r: ResolvedSandbox,
+  feedback: ScopedFeedback,
+  timeout?: number,
+  provisionSlot?: ProvisionSlot,
+): Promise<Sandbox> {
+  // 自定义 provider(defineSandbox):不认 provider 名,直接调用用户给的 create();
+  // feedback 已绑定到 sandbox.create 阶段(见 docs/feature/sandbox/library.md)。
+  if (r.create) return r.create({ timeout, runtime: r.runtime, feedback });
   switch (r.provider) {
     case "docker": {
-      const { DockerSandbox, classifyProvisionError } = await import("./docker.ts").catch(() => {
+      const { DockerSandbox, classifyProvisionError, reconcileProvision } = await import("./docker.ts").catch(() => {
         throw new Error(t("sandbox.dependencyMissing.docker"));
       });
+      // 一次性 provision token:歧义类失败重试前按它对账(销毁可能已创建的实例再重建)。
+      const token = randomUUID();
       return withProvisionRetry(
-        () => DockerSandbox.create({ timeout, runtime: r.runtime, image: r.image }),
+        () => DockerSandbox.create({ timeout, runtime: r.runtime, image: r.image, feedback, provisionToken: token }),
         classifyProvisionError,
         provisionSlot,
+        feedback,
+        () => reconcileProvision(token),
       );
     }
     case "vercel": {
       const { VercelSandbox, classifyProvisionError } = await import("./vercel.ts").catch(() => {
         throw new Error(t("sandbox.dependencyMissing.vercel"));
       });
+      // vercel SDK 没有按元数据检索实例的通道:不传 reconcile,歧义类第一次抛出。
       return withProvisionRetry(
-        () => VercelSandbox.create({ timeout, runtime: r.runtime, snapshotId: r.snapshotId }),
+        () => VercelSandbox.create({ timeout, runtime: r.runtime, snapshotId: r.snapshotId, feedback }),
         classifyProvisionError,
         provisionSlot,
+        feedback,
       );
     }
     case "e2b": {
-      const { E2BSandbox, classifyProvisionError } = await import("./e2b.ts").catch(() => {
+      const { E2BSandbox, classifyProvisionError, reconcileProvision } = await import("./e2b.ts").catch(() => {
         throw new Error(t("sandbox.dependencyMissing.e2b"));
       });
+      const token = randomUUID();
       return withProvisionRetry(
-        () => E2BSandbox.create({ timeout, runtime: r.runtime, template: r.template }),
+        () => E2BSandbox.create({ timeout, runtime: r.runtime, template: r.template, provisionToken: token }),
         classifyProvisionError,
         provisionSlot,
+        feedback,
+        () => reconcileProvision(token),
       );
     }
     default:

package/src/sandbox/retry.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/sandbox/cases.md
 import { describe, expect, it, vi } from "vitest";
 import { withProvisionRetry, type ProvisionSlot } from "./retry.ts";
 
@@ -41,6 +42,75 @@ describe("withProvisionRetry", () => {
     expect(calls).toEqual([]);
   });
 
+  it("throws an ambiguous error on the first attempt when no reconcile channel exists", async () => {
+    const err = new Error("fetch failed");
+    let attempts = 0;
+    await expect(
+      withProvisionRetry(
+        async () => {
+          attempts += 1;
+          throw err;
+        },
+        () => "ambiguous",
+      ),
+    ).rejects.toBe(err);
+    expect(attempts).toBe(1);
+  });
+
+  it("reconciles before every retry, including rejected-class errors like rate_limit", async () => {
+    vi.useFakeTimers();
+    try {
+      const order: string[] = [];
+      let attempts = 0;
+      const promise = withProvisionRetry(
+        async () => {
+          attempts += 1;
+          order.push(`create#${attempts}`);
+          if (attempts === 1) throw new Error("rate limited");
+          return "sandbox";
+        },
+        () => "rate_limit",
+        undefined,
+        undefined,
+        async () => {
+          order.push("reconcile");
+        },
+      );
+      await vi.runAllTimersAsync();
+      await expect(promise).resolves.toBe("sandbox");
+      // create() 闭包跨多个请求,429 可能来自实例已创建之后的初始化请求——拒绝类也必须先对账。
+      expect(order).toEqual(["create#1", "reconcile", "create#2"]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("aborts the retry and rethrows the original error when reconcile fails", async () => {
+    vi.useFakeTimers();
+    try {
+      const createErr = new Error("rate limited");
+      let attempts = 0;
+      const promise = withProvisionRetry(
+        async () => {
+          attempts += 1;
+          throw createErr;
+        },
+        () => "rate_limit",
+        undefined,
+        undefined,
+        async () => {
+          throw new Error("list also rate limited");
+        },
+      );
+      const assertion = expect(promise).rejects.toBe(createErr);
+      await vi.runAllTimersAsync();
+      await assertion;
+      expect(attempts).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("releases the slot before backing off and reacquires it before retrying", async () => {
     vi.useFakeTimers();
     try {

package/src/sandbox/retry.ts

@@ -1,8 +1,13 @@
 // provider 无关的 provisioning 退避重试:createProvider()(resolve.ts)对每个内置
 // provider 的 create() 套这一层。只有各 provider 自己的 classifyProvisionError 判为
-// 可重试(目前仅 rate_limit)的错误才会退避重试;其它错误第一次就抛出。
+// 可重试的错误才会退避重试;其它错误第一次就抛出。防泄漏的两道防线
+// (见 docs/feature/sandbox/architecture.md「Provisioning 失败与重试」)中,这里承担
+// 「重试前对账」;kill-on-failure 在各 provider 的 create() 内部。
 
-import { isRetryableProvisionError, type SandboxProvisionErrorKind } from "./errors.ts";
+import { isRejectedProvisionError, isRetryableProvisionError, type SandboxProvisionErrorKind } from "./errors.ts";
+import { t } from "../i18n/index.ts";
+import { reportActivity, reportDiagnostic } from "../runner/feedback/sink.ts";
+import type { ScopedFeedback } from "../types.ts";
 
 const MAX_ATTEMPTS = 4;
 const BASE_DELAY_MS = 1000;
@@ -25,20 +30,57 @@ export async function withProvisionRetry<T>(
   create: () => Promise<T>,
   classify: (e: unknown) => SandboxProvisionErrorKind,
   slot?: ProvisionSlot,
+  feedback?: ScopedFeedback,
+  /**
+   * 对账钩子:按 provision token 检索远端、销毁可能已创建的实例。提供时**每次重试前都执行**,
+   * 不区分拒绝类还是歧义类——被重试的 create() 闭包跨多个请求,一个 429 可能来自实例已创建
+   * 之后的初始化请求,分类不保证远端没有实例。对账排在退避睡眠之后(紧跟失败发出的检索大概率
+   * 同样被限流);对账抛错即放弃重试、抛回原始 create 错误。没有对账通道的 provider 不传——
+   * 歧义类第一次抛出:宁可判死一个 attempt,不留一台计费的无主实例
+   * (见 docs/feature/sandbox/architecture.md)。
+   */
+  reconcile?: () => Promise<void>,
 ): Promise<T> {
   for (let attempt = 0; ; attempt++) {
     try {
       return await create();
     } catch (e) {
-      if (!isRetryableProvisionError(classify(e)) || attempt >= MAX_ATTEMPTS - 1) throw e;
+      const kind = classify(e);
+      if (!isRetryableProvisionError(kind) || attempt >= MAX_ATTEMPTS - 1) throw e;
+      // 歧义类:远端可能已有实例,没有对账通道就不能重试,第一次抛出。
+      if (!isRejectedProvisionError(kind) && !reconcile) throw e;
       // 退避期间只是在睡觉,不是在真的创建沙箱:攥着并发槽位陪跑 setTimeout 会让被限流的
       // provider 把整批并发名额拖垮成"看起来卡在个位数并发"——先还名额,睡醒了再排队要回来。
       if (slot) await slot.release();
+      // 「activity」而非「diagnostic」—— 这是正常的退避进度,不是需要去重/永久留痕的
+      // warning(与 docker.ts 的镜像拉取进度、vercel.ts 的 session rotate 通知同一个理由,
+      // 见 sink.ts 的 reportActivity 说明)。让 human dashboard 的 active slot 在整个退避
+      // 窗口里有可见更新,而不是冻结到重试成功或耗尽为止。
+      const delayMs = delayFor(attempt);
+      const message = t("sandbox.provisionRetry", { delayMs: Math.round(delayMs), attempt: attempt + 1, maxAttempts: MAX_ATTEMPTS }).trimEnd();
+      if (feedback) feedback.progress({ message });
+      else reportActivity(message);
       try {
-        await new Promise((resolve) => setTimeout(resolve, delayFor(attempt)));
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
       } finally {
         if (slot) await slot.reacquire();
       }
+      if (reconcile) {
+        try {
+          await reconcile();
+        } catch (reconcileError) {
+          // 对账是重试的硬前置:查不到账就重试与盲重试无异。放弃重试,留 diagnostic,
+          // 抛回原始 create 错误(对账失败不掩盖它)。
+          const diagnostic = {
+            code: "sandbox-provision-reconcile-failed",
+            level: "warning" as const,
+            message: t("sandbox.provisionReconcileFailed", { error: String(reconcileError) }).trimEnd(),
+          };
+          if (feedback) feedback.diagnostic(diagnostic);
+          else reportDiagnostic({ key: diagnostic.code, severity: diagnostic.level, message: diagnostic.message });
+          throw e;
+        }
+      }
     }
   }
 }

package/src/sandbox/types.ts

@@ -1,12 +1,18 @@
 // sandbox 域类型:Sandbox 接口、provider spec(可辨识联合)、命令与文件 IO 的形状。
 // 「在哪里跑、如何隔离」的全部契约在这里;provider 实现见本目录各文件,分发见 resolve.ts。
 
-import type { AgentSetup, AgentTeardown } from "../agents/types.ts";
+import type { Cleanup, ScopedFeedback } from "../shared/types.ts";
 
 export interface CommandResult {
   stdout: string;
   stderr: string;
   exitCode: number;
+  /**
+   * 这次执行的命令摘要(有界、已脱敏,与时间树 command 节点同一份文案)。由执行面在最外层
+   * 公开调用处附加;直接从 provider 拿到的裸结果可能没有。断言失败时用作 evidence
+   * (`commandSucceeded()` 的「命令行本身」),消费方按可选字段读。
+   */
+  command?: string;
 }
 
 export interface SandboxFile {
@@ -82,15 +88,33 @@ export type SandboxRuntime = "node20" | "node24";
  */
 export interface SandboxHooks<Self> {
   /** 已挂载的 setup 钩子,按追加顺序保存(内部读取,一般用不到)。 */
-  readonly setupHooks?: readonly AgentSetup[];
+  readonly setupHooks?: readonly SandboxHook[];
   /** 已挂载的 teardown 钩子,按追加顺序保存,执行时逆序(内部读取,一般用不到)。 */
-  readonly teardownHooks?: readonly AgentTeardown[];
+  readonly teardownHooks?: readonly SandboxHook[];
   /** 追加一个沙箱级 setup 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
-  setup(fn: AgentSetup): Self;
+  setup(fn: SandboxHook): Self;
   /** 追加一个沙箱级 teardown 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
-  teardown(fn: AgentTeardown): Self;
+  teardown(fn: SandboxHook): Self;
 }
 
+/**
+ * Sandbox hook 的窄上下文:只有 `experimentId`、`signal` 与作用域绑定的 `progress/diagnostic`,
+ * 不借用包含 session / model / telemetry 的完整 `AgentContext`
+ * (见 docs/feature/sandbox/library.md「环境层生命周期钩子」)。
+ */
+export interface SandboxHookContext extends ScopedFeedback {
+  /** 路径推导出的实验 id;不经 experiment 跑时是 undefined。跨 attempt 状态按它分区。 */
+  readonly experimentId?: string;
+  /** 本次 attempt 的中止信号。 */
+  readonly signal: AbortSignal;
+}
+
+/** 沙箱级生命周期钩子(`.setup()` / `.teardown()` 链式挂载);`setup` 可返回 cleanup 闭包。 */
+export type SandboxHook = (
+  sandbox: Sandbox,
+  ctx: SandboxHookContext,
+) => void | Cleanup | Promise<void | Cleanup>;
+
 /**
  * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/feature/sandbox/library.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
@@ -125,7 +149,13 @@ export interface CustomSandboxSpec extends SandboxHooks<CustomSandboxSpec> {
   readonly provider: string;
   readonly runtime?: SandboxRuntime;
   readonly recommendedConcurrency?: number;
-  readonly create: (opts: { timeout?: number; runtime?: SandboxRuntime }) => Promise<Sandbox>;
+  /** `feedback` 绑定到 `sandbox.create` 阶段:分配实例 / 拉镜像 / 恢复 snapshot 的进度与诊断走它。 */
+  readonly create: (opts: { timeout?: number; runtime?: SandboxRuntime; feedback: ScopedFeedback }) => Promise<Sandbox>;
+  /**
+   * 「哪些参数可发布」的投影,进结果快照的 ExperimentRunInfo.sandbox.params;
+   * 未实现时只落 provider 名。token、凭据路径永远不该出现在返回值里。
+   */
+  readonly publicConfig?: () => Record<string, import("../shared/types.ts").JsonValue>;
 }
 
 export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec | CustomSandboxSpec;
@@ -145,6 +175,14 @@ export interface CommandOptions {
    * 不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
    */
   stream?: boolean;
+  /**
+   * 命令 stdout 每到一块就调用一次。回调只用于运行中的短命反馈；完整 stdout 仍会原样
+   * 出现在返回的 `CommandResult` 里。provider 不支持真流时，至少会在命令结束后按完整
+   * stdout 调用一次，不能静默丢掉。
+   */
+  onStdout?: (chunk: string) => void | Promise<void>;
+  /** `onStdout` 的 stderr 对应物；完整 stderr 仍保留在 `CommandResult`。 */
+  onStderr?: (chunk: string) => void | Promise<void>;
   /**
    * 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
    * 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。

package/src/sandbox/vercel.ts

@@ -14,8 +14,8 @@ import { readSourceFilesByList } from "./source-files.ts";
 import { collectLocalFiles } from "./local-files.ts";
 import { resolveSandboxPath } from "./paths.ts";
 import { t } from "../i18n/index.ts";
-import { beforeExternalTerminalWrite } from "../tty-line.ts";
-import type { SandboxProvisionErrorKind } from "./errors.ts";
+import { reportActivity, reportDiagnostic } from "../runner/feedback/sink.ts";
+import { classifyProvisionErrorFallback, type SandboxProvisionErrorKind } from "./errors.ts";
 
 /**
  * vercel SDK 对单次 fetch 的 429 已有内部重试(见 @vercel/sandbox 的 with-retry.js,
@@ -23,7 +23,9 @@ import type { SandboxProvisionErrorKind } from "./errors.ts";
  * 响应的 APIError,或 create() 轮询 session 状态过程里撞到的限流,都会走到这里。
  */
 export function classifyProvisionError(e: unknown): SandboxProvisionErrorKind {
-  return e instanceof APIError && e.response.status === 429 ? "rate_limit" : "unknown";
+  if (e instanceof APIError && e.response.status === 429) return "rate_limit";
+  // SDK 没有按元数据检索实例的通道:歧义类不重试、第一次抛出(见 retry.ts 的 reconcile 语义)。
+  return classifyProvisionErrorFallback(e);
 }
 
 // Vercel Sandbox 的默认工作区路径(SDK writeFiles 默认落这里)。
@@ -70,7 +72,7 @@ export class VercelSandbox implements Sandbox {
   }
 
   static async create(
-    opts: { timeout?: number; runtime?: "node20" | "node24"; snapshotId?: string } = {},
+    opts: { timeout?: number; runtime?: "node20" | "node24"; snapshotId?: string; feedback?: import("../types.ts").ScopedFeedback } = {},
   ): Promise<VercelSandbox> {
     // Vercel 支持 node22/node24/node26/python3.13;node20 回退到 node22。
     const runtime = opts.runtime === "node20" ? "node22" : (opts.runtime ?? "node24");
@@ -122,22 +124,29 @@ export class VercelSandbox implements Sandbox {
       // 挂起的 stop(最长 15s)不该拖住触发 rotate 的那条命令,还烧新 session 的时长。
       // 失败只警告不静默(旧的到 session timeout 也会被平台回收)。
       void withTimeout(oldVsb.stop(), STOP_OLD_SESSION_TIMEOUT_MS).catch((stopErr) => {
-        beforeExternalTerminalWrite();
-        console.error(
-          `[VercelSandbox] warning: failed to stop rotated-out session, microVM may leak until session timeout: ${String(stopErr)}`,
-        );
+        reportDiagnostic({
+          key: "vercel-stop-rotated-session-failed",
+          severity: "warning",
+          message: `[VercelSandbox] warning: failed to stop rotated-out session, microVM may leak until session timeout: ${String(stopErr)}`,
+          data: { sandboxId: this.sandboxId, error: String(stopErr) },
+        });
       });
-      beforeExternalTerminalWrite();
-      console.error(t("vercel.rotated", {
-        seconds: Math.round(elapsed / 1000),
-        sessionId: newVsb.currentSession().sessionId,
-      }));
+      reportActivity(
+        t("vercel.rotated", {
+          seconds: Math.round(elapsed / 1000),
+          sessionId: newVsb.currentSession().sessionId,
+        }).trimEnd(),
+      );
     } catch (err) {
-      beforeExternalTerminalWrite();
-      console.error(t("vercel.rotateFailed", {
-        seconds: Math.round(elapsed / 1000),
-        error: String(err),
-      }));
+      reportDiagnostic({
+        key: "vercel-rotate-failed",
+        severity: "warning",
+        message: t("vercel.rotateFailed", {
+          seconds: Math.round(elapsed / 1000),
+          error: String(err),
+        }).trimEnd(),
+        data: { sandboxId: this.sandboxId, error: String(err) },
+      });
     }
   }
 
@@ -152,9 +161,15 @@ export class VercelSandbox implements Sandbox {
       // 显式设 per-command timeout 防止长跑命令(npm build/install)被流截断。
       timeoutMs: this.commandTimeoutMs,
     });
+    const stdout = await finished.stdout();
+    const stderr = await finished.stderr();
+    // Vercel SDK 的命令 API 只在结束后给完整输出；仍兑现 CommandOptions 回调的
+    // 「至少一次」语义，让 adapter 不必按 provider 分叉。
+    if (stdout) await opts.onStdout?.(stdout);
+    if (stderr) await opts.onStderr?.(stderr);
     return {
-      stdout: await finished.stdout(),
-      stderr: await finished.stderr(),
+      stdout,
+      stderr,
       exitCode: finished.exitCode,
     };
   }
@@ -220,6 +235,14 @@ export class VercelSandbox implements Sandbox {
     await this.vsb.stop();
   }
 
+  /**
+   * 留存休眠(suspend):vercel `stop`——sandbox 默认持久,stop 保存文件系统,之后经
+   * `Sandbox.get` 恢复(SDK 原生能力);内存态不保留,唤醒后进程要重新启动。
+   */
+  async suspend(): Promise<void> {
+    await this.vsb.stop();
+  }
+
   async downloadFile(path: string): Promise<Buffer> {
     const absPath = resolveSandboxPath(this.workdir, path);
     const buf = await this.vsb.readFileToBuffer({ path: absPath });

package/src/scoring/collector.ts

@@ -9,27 +9,50 @@ import { formatThrown } from "../util.ts";
 export interface EvalScore {
   score: number;
   detail?: string;
-  /** 这条分数是看着什么材料算出来的(judge 收到的输入,或 t.check 失败时实际被检查的值);供 view 展开排查「为什么是这个分」。 */
+  /** 期望条件的有界文本预览(如 `contains "Brooklyn"`),失败时供 show/view 直接展示。 */
+  expected?: string;
+  /** 实际值的有界文本预览(被检查值 / 作用域内实际调用清单)。 */
+  received?: string;
+  /** 这条分数是看着什么材料算出来的(judge 收到的输入等);供 view 展开排查「为什么是这个分」。 */
   evidence?: string;
 }
 
-/** 一条尚未评估的断言。evaluate 在 finalize 时拿到完整运行结果再算分 [0,1]。 */
+/** evaluate 返回它表示「这条断言评不了」:证据通道不完整 / judge 未解析到模型等。 */
+export interface EvalUnavailable {
+  unavailable: true;
+  /** 机器可读原因,如 "judge-model-unresolved"、"coverage:actions=partial"。 */
+  reason: string;
+}
+
+/** 构造 EvalUnavailable 的便捷工厂(scoped / judge 断言用)。 */
+export function unavailable(reason: string): EvalUnavailable {
+  return { unavailable: true, reason };
+}
+
+function isUnavailable(v: unknown): v is EvalUnavailable {
+  return typeof v === "object" && v !== null && (v as EvalUnavailable).unavailable === true;
+}
+
+/** 一条尚未评估的断言。evaluate 在 finalize 时拿到完整运行结果再算分 [0,1](或报告评不了)。 */
 export interface Spec {
   name: string;
   severity: Severity;
   threshold?: number;
+  /** 作者用 .optional() 显式允许该断言证据缺席;unavailable 只保留在记录里,不影响判定。 */
+  optional?: true;
   detail?: string;
-  /** 所属分组(t.group 标题,可嵌套用 › 连接)。纯组织用,不影响打分。 */
-  group?: string;
+  /** 所属分组路径(外层在前的 t.group 标题数组)。纯组织用,不影响打分。 */
+  groupPath?: string[];
   /** 断言在 eval 源码里的调用点(record 时栈回溯抠出)。 */
   loc?: SourceLoc;
-  evaluate(ctx: ScoringContext): number | EvalScore | Promise<number | EvalScore>;
+  evaluate(ctx: ScoringContext): number | EvalScore | EvalUnavailable | Promise<number | EvalScore | EvalUnavailable>;
 }
 
-/** 作者拿到的可链式句柄,改严重度 / 阈值(回头改 spec)。 */
+/** 作者拿到的可链式句柄,改严重度 / 阈值 / optional(回头改 spec)。 */
 export interface RecordHandle {
   atLeast(threshold: number): RecordHandle;
   gate(threshold?: number): RecordHandle;
+  optional(): RecordHandle;
 }
 
 export class AssertionCollector {
@@ -40,7 +63,7 @@ export class AssertionCollector {
     return this.specs.length > 0;
   }
 
-  /** t.group(title, fn) 期间入栈;栈内 record 的断言都打上当前(嵌套则 › 连接)分组标题。 */
+  /** t.group(title, fn) 期间入栈;栈内 record 的断言都打上当前分组路径(嵌套时外层在前)。 */
   async withGroup<T>(title: string, fn: () => Promise<T> | T): Promise<T> {
     this.groupStack.push(title);
     try {
@@ -51,8 +74,8 @@ export class AssertionCollector {
   }
 
   record(spec: Spec): RecordHandle {
-    if (spec.group === undefined && this.groupStack.length > 0) {
-      spec.group = this.groupStack.join(" › ");
+    if (spec.groupPath === undefined && this.groupStack.length > 0) {
+      spec.groupPath = this.groupStack.slice();
     }
     if (spec.loc === undefined) spec.loc = captureLoc();
     this.specs.push(spec);
@@ -67,6 +90,10 @@ export class AssertionCollector {
         spec.threshold = threshold;
         return handle;
       },
+      optional() {
+        spec.optional = true;
+        return handle;
+      },
     };
     return handle;
   }
@@ -74,16 +101,32 @@ export class AssertionCollector {
   async finalize(ctx: ScoringContext): Promise<AssertionResult[]> {
     const out: AssertionResult[] = [];
     for (const spec of this.specs) {
+      const base = {
+        name: spec.name,
+        severity: spec.severity,
+        ...(spec.optional ? { optional: true as const } : {}),
+        ...(spec.detail !== undefined ? { detail: spec.detail } : {}),
+        ...(spec.groupPath !== undefined ? { groupPath: spec.groupPath } : {}),
+        ...(spec.loc !== undefined ? { loc: spec.loc } : {}),
+      };
       let score = 0;
       let detail = spec.detail;
+      let expected: string | undefined;
+      let received: string | undefined;
       let evidence: string | undefined;
       try {
         const raw = await spec.evaluate(ctx);
+        if (isUnavailable(raw)) {
+          out.push({ ...base, outcome: "unavailable", reason: raw.reason });
+          continue;
+        }
         if (typeof raw === "number") {
           score = raw;
         } else {
           score = raw.score;
           if (raw.detail) detail = detail ? `${detail}; ${raw.detail}` : raw.detail;
+          expected = raw.expected;
+          received = raw.received;
           evidence = raw.evidence;
         }
       } catch (e) {
@@ -92,16 +135,16 @@ export class AssertionCollector {
           error: formatThrown(e),
         })}`;
       }
+      const passed = computePassed(spec.severity, spec.threshold, score);
       out.push({
-        name: spec.name,
-        severity: spec.severity,
-        threshold: spec.threshold,
+        ...base,
+        ...(detail !== undefined ? { detail } : {}),
+        outcome: passed ? "passed" : "failed",
         score,
-        passed: computePassed(spec.severity, spec.threshold, score),
-        detail,
-        evidence,
-        group: spec.group,
-        loc: spec.loc,
+        ...(spec.threshold !== undefined ? { threshold: spec.threshold } : {}),
+        ...(expected !== undefined ? { expected } : {}),
+        ...(received !== undefined ? { received } : {}),
+        ...(evidence !== undefined ? { evidence } : {}),
       });
     }
     return out;