niceeval 0.6.1 → 0.7.0

package/src/sandbox/io-retry.test.ts

@@ -0,0 +1,58 @@
+// cases: docs/engineering/unit-tests/sandbox/cases.md
+import { describe, expect, it, vi } from "vitest";
+import { classifySandboxIoError } from "./errors.ts";
+import { withSandboxIoRetry } from "./io-retry.ts";
+
+describe("classifySandboxIoError", () => {
+  it("recognizes the nested fetch failure shape emitted by E2B uploads", () => {
+    const error = new TypeError("fetch failed", { cause: Object.assign(new Error("reset"), { code: "ECONNRESET" }) });
+    expect(classifySandboxIoError(error)).toBe("network");
+  });
+
+  it("recognizes status-bearing rate limits and service outages", () => {
+    expect(classifySandboxIoError({ response: { status: 429 } })).toBe("rate_limit");
+    expect(classifySandboxIoError({ statusCode: 503 })).toBe("service_unavailable");
+  });
+
+  it("does not retry cancellation, sandbox termination, or deterministic file errors", () => {
+    expect(classifySandboxIoError(Object.assign(new Error("aborted"), { name: "AbortError" }))).toBe("unknown");
+    expect(classifySandboxIoError(new Error("Sandbox was terminated"))).toBe("unknown");
+    expect(classifySandboxIoError(new Error("ENOENT: no such file"))).toBe("unknown");
+  });
+});
+
+describe("withSandboxIoRetry", () => {
+  it("retries a transient failure with bounded exponential backoff", async () => {
+    const sleep = vi.fn(async () => {});
+    const onRetry = vi.fn();
+    let attempts = 0;
+    const result = await withSandboxIoRetry(async () => {
+      attempts += 1;
+      if (attempts < 3) throw new TypeError("fetch failed");
+      return "ok";
+    }, { baseDelayMs: 100, random: () => 0.5, sleep, onRetry });
+
+    expect(result).toBe("ok");
+    expect(attempts).toBe(3);
+    expect(sleep.mock.calls).toEqual([[100], [200]]);
+    expect(onRetry.mock.calls.map(([event]) => event.kind)).toEqual(["network", "network"]);
+  });
+
+  it("preserves the original error after the retry limit", async () => {
+    const error = new TypeError("fetch failed");
+    await expect(withSandboxIoRetry(
+      async () => { throw error; },
+      { maxAttempts: 2, baseDelayMs: 0, sleep: async () => {} },
+    )).rejects.toBe(error);
+  });
+
+  it("does not retry deterministic errors", async () => {
+    let attempts = 0;
+    const error = new Error("ENOENT: missing");
+    await expect(withSandboxIoRetry(async () => {
+      attempts += 1;
+      throw error;
+    })).rejects.toBe(error);
+    expect(attempts).toBe(1);
+  });
+});

package/src/sandbox/io-retry.ts

@@ -0,0 +1,45 @@
+// 已创建 Sandbox 的幂等文件 IO 重试。命令执行、appendLog、stop 不经过这里：
+// 它们可能有不可重复的副作用，框架不能在调用者不知情时重跑。
+
+import {
+  classifySandboxIoError,
+  isRetryableSandboxIoError,
+  type SandboxIoErrorKind,
+} from "./errors.ts";
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 250;
+
+export interface SandboxIoRetryOptions {
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  classify?: (error: unknown) => SandboxIoErrorKind;
+  /** 内部可观察挂点；runner feedback 接入后由统一包装层注入。 */
+  onRetry?: (event: { attempt: number; delayMs: number; kind: SandboxIoErrorKind; error: unknown }) => void;
+  /** 仅供确定性单测注入。 */
+  random?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export async function withSandboxIoRetry<T>(
+  operation: () => Promise<T>,
+  options: SandboxIoRetryOptions = {},
+): Promise<T> {
+  const maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+  const baseDelayMs = Math.max(0, options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS);
+  const classify = options.classify ?? classifySandboxIoError;
+  const random = options.random ?? Math.random;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      const kind = classify(error);
+      if (!isRetryableSandboxIoError(kind) || attempt >= maxAttempts) throw error;
+      const delayMs = baseDelayMs * 2 ** (attempt - 1) * (0.5 + random());
+      options.onRetry?.({ attempt, delayMs, kind, error });
+      await sleep(delayMs);
+    }
+  }
+}

package/src/sandbox/keep-registry.test.ts

@@ -0,0 +1,86 @@
+// cases: docs/engineering/unit-tests/sandbox/cases.md
+// 留存注册表的单测:逐条目文件、原子写、发现规则、更新与删除(见 docs/feature/sandbox/architecture.md)。
+
+import { afterEach, describe, expect, it } from "vitest";
+import { mkdir, mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  findNiceevalRoot,
+  keptEntryId,
+  readKeptEntries,
+  removeKeptEntry,
+  updateKeptEntry,
+  writeKeptEntry,
+  type KeptSandboxEntry,
+} from "./keep-registry.ts";
+
+let roots: string[] = [];
+async function makeRoot(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "niceeval-keep-"));
+  roots.push(dir);
+  return dir;
+}
+afterEach(async () => {
+  await Promise.all(roots.map((r) => rm(r, { recursive: true, force: true })));
+  roots = [];
+});
+
+function entry(over: Partial<KeptSandboxEntry> = {}): KeptSandboxEntry {
+  return {
+    sandboxId: "a3f9c2d1",
+    provider: "docker",
+    evalId: "onboarding/tool-first",
+    attempt: 1,
+    experimentId: "local/tool-first",
+    locator: "@1x7f3q9k",
+    verdict: "errored",
+    keptAt: "2026-07-14T15:02:00.000Z",
+    workdir: "/workspace",
+    state: "alive",
+    ...over,
+  };
+}
+
+describe("kept-sandbox registry", () => {
+  it("逐条目文件:写入 → 读回 → 更新 state → 删除并同步目录", async () => {
+    const root = await makeRoot();
+    const niceeval = join(root, ".niceeval");
+    await writeKeptEntry(niceeval, entry());
+    const id = keptEntryId("docker", "a3f9c2d1");
+
+    const { entries } = await readKeptEntries(niceeval);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.id).toBe(id);
+    expect(entries[0]!.entry.locator).toBe("@1x7f3q9k");
+    expect(entries[0]!.entry.state).toBe("alive");
+
+    expect(await updateKeptEntry(niceeval, id, { state: "dormant" })).toBe(true);
+    expect((await readKeptEntries(niceeval)).entries[0]!.entry.state).toBe("dormant");
+
+    await removeKeptEntry(niceeval, id);
+    expect((await readKeptEntries(niceeval)).entries).toHaveLength(0);
+    // 临时文件不残留
+    expect((await readdir(join(niceeval, "sandboxes"))).filter((f) => f.endsWith(".tmp"))).toHaveLength(0);
+  });
+
+  it("不同 provider+sandboxId 各自成条目,互不覆盖", async () => {
+    const root = await makeRoot();
+    const niceeval = join(root, ".niceeval");
+    await writeKeptEntry(niceeval, entry());
+    await writeKeptEntry(niceeval, entry({ sandboxId: "b81e07aa", verdict: "failed" }));
+    const { entries } = await readKeptEntries(niceeval);
+    expect(entries).toHaveLength(2);
+  });
+
+  it("注册表发现:从子目录向上找最近的 .niceeval;找不到返回 undefined", async () => {
+    const root = await makeRoot();
+    const niceeval = join(root, ".niceeval");
+    await mkdir(join(niceeval, "sandboxes"), { recursive: true });
+    const deep = join(root, "a", "b", "c");
+    await mkdir(deep, { recursive: true });
+    expect(await findNiceevalRoot(deep)).toBe(niceeval);
+    const outside = await makeRoot();
+    expect(await findNiceevalRoot(outside)).toBeUndefined();
+  });
+});

package/src/sandbox/keep-registry.ts

@@ -0,0 +1,142 @@
+// 留存沙箱的持久注册表:`.niceeval/sandboxes/` 下的逐条目文件(不是多个 attempt 竞争改写的
+// 一份 JSON)。entry id 由 provider + sandboxId 做稳定散列;每条先写同目录临时文件、fsync 文件后
+// rename 成 <entry-id>.json,再 fsync 目录——不同 attempt 与不同 niceeval 进程不会覆盖彼此。
+// 契约见 docs/feature/sandbox/architecture.md「留存(keep)与注册表」。
+
+import { createHash } from "node:crypto";
+import { mkdir, open, readdir, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import type { Verdict } from "../types.ts";
+
+/** 一条留存登记项(逐条目文件的 JSON 形状)。 */
+export interface KeptSandboxEntry {
+  sandboxId: string;
+  provider: string;
+  evalId: string;
+  attempt: number;
+  experimentId?: string;
+  locator: string;
+  verdict: Verdict;
+  keptAt: string;
+  workdir: string;
+  /** provider 原生的进入命令(直连与审计用);日常入口是 `niceeval sandbox enter`。 */
+  enter?: string;
+  /** 现场可找回的截止时刻——provider 声明了保留期限才写(vercel 写,e2b pause 无限期保留则不写)。 */
+  expiresAt?: string;
+  /** alive = 实例在跑(suspend 失败或 --leave-running);dormant = 休眠可唤醒;expired = 现场已没了。 */
+  state: "alive" | "dormant" | "expired";
+  /** 事后命令的条目级互斥凭据(enter 持有;stop 与另一个 enter 对同一条目直接拒绝)。 */
+  lease?: { holder: string; op: string; acquiredAt: string; ttlMs: number };
+}
+
+/** entry id:provider + sandboxId 的稳定散列(条目文件名)。 */
+export function keptEntryId(provider: string, sandboxId: string): string {
+  return createHash("sha256").update(`${provider}\n${sandboxId}`).digest("hex").slice(0, 12);
+}
+
+export function sandboxesDirOf(niceevalRoot: string): string {
+  return join(niceevalRoot, "sandboxes");
+}
+
+/**
+ * 注册表发现:从 cwd 向上找最近的 `.niceeval/`(与结果根发现同一规则)。
+ * 找不到返回 undefined,调用方报错并提示 `--run <结果根>`。
+ */
+export async function findNiceevalRoot(cwd: string): Promise<string | undefined> {
+  let current = resolve(cwd);
+  for (;;) {
+    const candidate = join(current, ".niceeval");
+    try {
+      const entries = await readdir(candidate);
+      void entries;
+      return candidate;
+    } catch {
+      // 不存在,继续向上
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+/** 原子写入一条登记项:临时文件 → fsync → rename → fsync 目录。 */
+export async function writeKeptEntry(niceevalRoot: string, entry: KeptSandboxEntry): Promise<void> {
+  const dir = sandboxesDirOf(niceevalRoot);
+  await mkdir(dir, { recursive: true });
+  const id = keptEntryId(entry.provider, entry.sandboxId);
+  const tmpPath = join(dir, `.${id}.${process.pid}.tmp`);
+  const finalPath = join(dir, `${id}.json`);
+  const handle = await open(tmpPath, "w");
+  try {
+    await handle.writeFile(JSON.stringify(entry, null, 2), "utf-8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(tmpPath, finalPath);
+  await fsyncDir(dir);
+}
+
+/** 读全部登记项(坏条目跳过并记名,不整体失败)。 */
+export async function readKeptEntries(
+  niceevalRoot: string,
+): Promise<{ entries: { id: string; entry: KeptSandboxEntry }[]; malformed: string[] }> {
+  const dir = sandboxesDirOf(niceevalRoot);
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    return { entries: [], malformed: [] };
+  }
+  const entries: { id: string; entry: KeptSandboxEntry }[] = [];
+  const malformed: string[] = [];
+  for (const file of files) {
+    if (!file.endsWith(".json") || file.startsWith(".")) continue;
+    try {
+      const raw = await readFile(join(dir, file), "utf-8");
+      entries.push({ id: file.slice(0, -".json".length), entry: JSON.parse(raw) as KeptSandboxEntry });
+    } catch {
+      malformed.push(file);
+    }
+  }
+  entries.sort((a, b) => a.entry.keptAt.localeCompare(b.entry.keptAt));
+  return { entries, malformed };
+}
+
+/** 更新一条登记项(读-改-原子写;字段浅合并)。条目不存在时静默返回 false。 */
+export async function updateKeptEntry(
+  niceevalRoot: string,
+  id: string,
+  patch: Partial<KeptSandboxEntry> | ((entry: KeptSandboxEntry) => KeptSandboxEntry),
+): Promise<boolean> {
+  const path = join(sandboxesDirOf(niceevalRoot), `${id}.json`);
+  let entry: KeptSandboxEntry;
+  try {
+    entry = JSON.parse(await readFile(path, "utf-8")) as KeptSandboxEntry;
+  } catch {
+    return false;
+  }
+  const next = typeof patch === "function" ? patch(entry) : { ...entry, ...patch };
+  await writeKeptEntry(niceevalRoot, next);
+  return true;
+}
+
+/** 删除一条登记项并同步目录(只在实例成功销毁或确认已不存在后调用)。 */
+export async function removeKeptEntry(niceevalRoot: string, id: string): Promise<void> {
+  const dir = sandboxesDirOf(niceevalRoot);
+  await rm(join(dir, `${id}.json`), { force: true });
+  await fsyncDir(dir);
+}
+
+async function fsyncDir(dir: string): Promise<void> {
+  try {
+    const handle = await open(dir, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    // 平台不支持目录 fsync(如 Windows)时静默降级;rename 本身已是原子替换。
+  }
+}

package/src/sandbox/keep.ts

@@ -0,0 +1,178 @@
+// 留存生命周期的 sandbox/ 域内路由:in-run 的 suspend(留存提交后转休眠)与事后命令
+// (`niceeval sandbox list/enter/stop`)用的 detached 能力(不需要原来的 run 进程或 Sandbox
+// 实例还活着)。provider 名的行为分支只允许出现在 sandbox/ 内(见 docs/architecture.md);
+// 运行器与评分路径不感知 provider 名。
+
+import type { Sandbox } from "../types.ts";
+
+/** 有留存能力的 provider 实例都带一个非公开接口成员 suspend()(Sandbox 接口不因留存扩大)。 */
+interface Suspendable {
+  suspend(): Promise<void>;
+}
+
+/** provider 是否参与留存(defineSandbox 自定义 provider 不参与,创建前报错)。 */
+export const KEEPABLE_PROVIDERS = new Set(["docker", "e2b", "vercel"]);
+
+/** in-run 的休眠:留存提交成功后由 Scope release 调用(sandbox.suspend 阶段,有界计时)。 */
+export async function suspendSandbox(sandbox: Sandbox): Promise<void> {
+  const suspend = (sandbox as unknown as Partial<Suspendable>).suspend;
+  if (typeof suspend !== "function") {
+    throw new Error(`sandbox provider has no suspend capability (sandboxId=${sandbox.sandboxId})`);
+  }
+  await suspend.call(sandbox);
+}
+
+/** provider 原生的进入命令(记进注册表供直连与审计;日常入口是 `niceeval sandbox enter`)。 */
+export function nativeEnterCommand(provider: string, sandboxId: string): string | undefined {
+  switch (provider) {
+    case "docker":
+      return `docker start ${sandboxId} && docker exec -it ${sandboxId} bash`;
+    case "e2b":
+      return `e2b sandbox connect ${sandboxId}`;
+    default:
+      return undefined;
+  }
+}
+
+export type DetachedState = "alive" | "dormant" | "expired";
+
+/** 事后核对现场状态(docker 问本地 daemon;云 provider 按实例状态核对,查不到 = expired)。 */
+export async function inspectDetached(provider: string, sandboxId: string): Promise<DetachedState> {
+  switch (provider) {
+    case "docker": {
+      try {
+        const { default: Docker } = await import("dockerode");
+        const info = await new Docker().getContainer(sandboxId).inspect();
+        return info.State?.Running ? "alive" : "dormant";
+      } catch {
+        return "expired";
+      }
+    }
+    case "e2b": {
+      try {
+        const { Sandbox: E2BSdkSandbox } = await import("e2b");
+        const list = (E2BSdkSandbox as unknown as {
+          list?: (opts?: Record<string, unknown>) => Promise<Array<{ sandboxId: string; state?: string }>>;
+        }).list;
+        if (typeof list !== "function") return "dormant";
+        const sandboxes = await list({ apiKey: process.env.E2B_API_KEY });
+        const hit = sandboxes.find((s) => s.sandboxId === sandboxId || s.sandboxId.startsWith(sandboxId));
+        if (!hit) return "expired";
+        return hit.state === "running" ? "alive" : "dormant";
+      } catch {
+        return "expired";
+      }
+    }
+    case "vercel": {
+      try {
+        const { Sandbox: VSandbox } = await import("@vercel/sandbox");
+        const get = (VSandbox as unknown as { get?: (opts: Record<string, unknown>) => Promise<unknown> }).get;
+        if (typeof get !== "function") return "dormant";
+        const found = await get({ sandboxId });
+        return found ? "dormant" : "expired";
+      } catch {
+        return "expired";
+      }
+    }
+    default:
+      return "expired";
+  }
+}
+
+/**
+ * detached 销毁:按注册表条目的 provider 名路由,不需要 Sandbox 实例。
+ * 返回 "stopped"(成功销毁)或 "already-gone"(实例已不存在,幂等);
+ * 其它错误上抛——调用方保留登记项并退出 1,不能把仍活着的资源从管理面隐藏掉。
+ */
+export async function destroyDetached(provider: string, sandboxId: string): Promise<"stopped" | "already-gone"> {
+  switch (provider) {
+    case "docker": {
+      const { default: Docker } = await import("dockerode");
+      const container = new Docker().getContainer(sandboxId);
+      try {
+        await container.remove({ force: true });
+        return "stopped";
+      } catch (e) {
+        if ((e as { statusCode?: number }).statusCode === 404) return "already-gone";
+        throw e;
+      }
+    }
+    case "e2b": {
+      const { Sandbox: E2BSdkSandbox } = await import("e2b");
+      const kill = (E2BSdkSandbox as unknown as {
+        kill?: (id: string, opts?: Record<string, unknown>) => Promise<boolean>;
+      }).kill;
+      if (typeof kill !== "function") throw new Error("this e2b SDK version has no detached kill capability");
+      const killed = await kill(sandboxId, { apiKey: process.env.E2B_API_KEY });
+      return killed ? "stopped" : "already-gone";
+    }
+    case "vercel": {
+      const { Sandbox: VSandbox } = await import("@vercel/sandbox");
+      const get = (VSandbox as unknown as {
+        get?: (opts: Record<string, unknown>) => Promise<{ stop(): Promise<void> } | null>;
+      }).get;
+      if (typeof get !== "function") throw new Error("this vercel SDK version has no detached get capability");
+      const found = await get({ sandboxId }).catch(() => null);
+      if (!found) return "already-gone";
+      await found.stop();
+      return "stopped";
+    }
+    default:
+      throw new Error(`provider "${provider}" has no detached stop channel`);
+  }
+}
+
+/** 唤醒休眠现场(enter / history / diff 前);docker start,云 provider 按 SDK 恢复。 */
+export async function wakeDetached(provider: string, sandboxId: string): Promise<void> {
+  switch (provider) {
+    case "docker": {
+      const { default: Docker } = await import("dockerode");
+      const container = new Docker().getContainer(sandboxId);
+      const info = await container.inspect();
+      if (!info.State?.Running) await container.start();
+      return;
+    }
+    case "e2b": {
+      const { Sandbox: E2BSdkSandbox } = await import("e2b");
+      const resume = (E2BSdkSandbox as unknown as {
+        resume?: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;
+        connect?: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;
+      });
+      if (typeof resume.resume === "function") {
+        await resume.resume(sandboxId, { apiKey: process.env.E2B_API_KEY });
+        return;
+      }
+      if (typeof resume.connect === "function") {
+        await resume.connect(sandboxId, { apiKey: process.env.E2B_API_KEY });
+        return;
+      }
+      throw new Error("this e2b SDK version has no resume capability");
+    }
+    default:
+      throw new Error(`provider "${provider}" has no wake channel`);
+  }
+}
+
+/** 送回休眠(enter 退出后 / history、diff 读完后)。 */
+export async function suspendDetached(provider: string, sandboxId: string): Promise<void> {
+  switch (provider) {
+    case "docker": {
+      const { default: Docker } = await import("dockerode");
+      await new Docker().getContainer(sandboxId).stop({ t: 5 });
+      return;
+    }
+    case "e2b": {
+      const { Sandbox: E2BSdkSandbox } = await import("e2b");
+      const pause = (E2BSdkSandbox as unknown as {
+        pause?: (id: string, opts?: Record<string, unknown>) => Promise<unknown>;
+      }).pause;
+      if (typeof pause === "function") {
+        await pause(sandboxId, { apiKey: process.env.E2B_API_KEY });
+        return;
+      }
+      throw new Error("this e2b SDK version has no detached pause capability");
+    }
+    default:
+      throw new Error(`provider "${provider}" has no suspend channel`);
+  }
+}

package/src/sandbox/paths.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/sandbox/cases.md
 import { describe, expect, it } from "vitest";
 import { normalizeSandboxPaths, resolveLocalPath, resolveSandboxPath } from "./paths.ts";
 import type { Sandbox } from "../types.ts";

package/src/sandbox/paths.ts

@@ -1,6 +1,7 @@
 import { posix } from "node:path";
 import { isAbsolute, resolve } from "node:path";
 import type { CommandOptions, Sandbox } from "../types.ts";
+import { withSandboxIoRetry } from "./io-retry.ts";
 
 export function resolveSandboxPath(workdir: string, path?: string): string {
   if (!path || path === ".") return workdir;
@@ -30,16 +31,26 @@ export function normalizeSandboxPaths(sandbox: Sandbox): Sandbox {
     },
     runCommand: (cmd, args, opts) => sandbox.runCommand(cmd, args, resolveCommandOptions(sandbox.workdir, opts)),
     runShell: (script, opts) => sandbox.runShell(script, resolveCommandOptions(sandbox.workdir, opts)),
-    readFile: (path) => sandbox.readFile(resolveSandboxPath(sandbox.workdir, path)),
-    fileExists: (path) => sandbox.fileExists(resolveSandboxPath(sandbox.workdir, path)),
-    readSourceFiles: (opts) => sandbox.readSourceFiles(opts),
-    writeFiles: (files, targetDir) => sandbox.writeFiles(files, resolveSandboxPath(sandbox.workdir, targetDir)),
-    uploadFiles: (files, targetDir) => sandbox.uploadFiles(files, resolveSandboxPath(sandbox.workdir, targetDir)),
+    readFile: (path) => withSandboxIoRetry(() => sandbox.readFile(resolveSandboxPath(sandbox.workdir, path))),
+    fileExists: (path) => withSandboxIoRetry(() => sandbox.fileExists(resolveSandboxPath(sandbox.workdir, path))),
+    readSourceFiles: (opts) => withSandboxIoRetry(() => sandbox.readSourceFiles(opts)),
+    writeFiles: (files, targetDir) => withSandboxIoRetry(
+      () => sandbox.writeFiles(files, resolveSandboxPath(sandbox.workdir, targetDir)),
+    ),
+    uploadFiles: (files, targetDir) => withSandboxIoRetry(
+      () => sandbox.uploadFiles(files, resolveSandboxPath(sandbox.workdir, targetDir)),
+    ),
     uploadDirectory: (localDir, targetDir, opts) =>
-      sandbox.uploadDirectory(localDir, resolveSandboxPath(sandbox.workdir, targetDir), opts),
+      withSandboxIoRetry(
+        () => sandbox.uploadDirectory(localDir, resolveSandboxPath(sandbox.workdir, targetDir), opts),
+      ),
     stop: () => sandbox.stop(),
     appendLog: sandbox.appendLog ? (line) => sandbox.appendLog!(line) : undefined,
-    downloadFile: (path) => sandbox.downloadFile(resolveSandboxPath(sandbox.workdir, path)),
-    uploadFile: (path, content) => sandbox.uploadFile(resolveSandboxPath(sandbox.workdir, path), content),
+    downloadFile: (path) => withSandboxIoRetry(
+      () => sandbox.downloadFile(resolveSandboxPath(sandbox.workdir, path)),
+    ),
+    uploadFile: (path, content) => withSandboxIoRetry(
+      () => sandbox.uploadFile(resolveSandboxPath(sandbox.workdir, path), content),
+    ),
   };
 }

package/src/sandbox/registry.ts

@@ -10,7 +10,7 @@
 
 import type { Sandbox } from "../types.ts";
 import { t } from "../i18n/index.ts";
-import { writeStderrLine } from "../tty-line.ts";
+import { reportDiagnostic } from "../runner/feedback/sink.ts";
 
 const live = new Set<Sandbox>();
 
@@ -22,6 +22,11 @@ export function registerSandbox(sb: Sandbox): void {
   live.add(sb);
 }
 
+/** 留存提交成功后把沙箱移出本次 run 的内存强清集合(不 stop——现场归持久注册表管理)。 */
+export function unregisterSandbox(sb: Sandbox): void {
+  live.delete(sb);
+}
+
 export function liveSandboxCount(): number {
   return live.size;
 }
@@ -41,7 +46,14 @@ export async function stopSandbox(sb: Sandbox, timeoutMs = DEFAULT_STOP_TIMEOUT_
     ]);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    writeStderrLine(t("sandbox.stopFailed", { id: sb.sandboxId, message: msg }));
+    // 稳定 key 不含具体 sandbox id:同一类失败(如 provider 限流导致大批 stop 超时)去重折叠成
+    // 一条永久事件、count 累加,而不是刷屏出几十行几乎相同的诊断;具体是哪个沙箱失败进 data。
+    reportDiagnostic({
+      key: "sandbox-stop-failed",
+      severity: "warning",
+      message: t("sandbox.stopFailed", { id: sb.sandboxId, message: msg }).trimEnd(),
+      data: { sandboxId: sb.sandboxId, message: msg },
+    });
   } finally {
     if (timer) clearTimeout(timer);
     live.delete(sb);
@@ -55,7 +67,12 @@ export async function stopSandbox(sb: Sandbox, timeoutMs = DEFAULT_STOP_TIMEOUT_
 export async function stopAllSandboxes(timeoutMs = DEFAULT_STOP_TIMEOUT_MS): Promise<number> {
   const all = [...live];
   if (all.length === 0) return 0;
-  writeStderrLine(t("sandbox.forceCleanup", { count: all.length }));
+  reportDiagnostic({
+    key: "sandbox-force-cleanup",
+    severity: "warning",
+    message: t("sandbox.forceCleanup", { count: all.length }).trimEnd(),
+    data: { count: all.length },
+  });
   await Promise.allSettled(all.map((sb) => stopSandbox(sb, timeoutMs)));
   return all.length;
 }