niceeval 0.8.1 → 0.9.1

package/src/agents/codex.test.ts

@@ -17,7 +17,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { codexAgent, installPlugins, type CodexPluginSpec } from "./codex.ts";
 import { createAgentSession } from "../context/session.ts";
-import type { AgentContext, AgentSetupManifest, CommandOptions, CommandResult, Sandbox, SandboxFile } from "../types.ts";
+import type { AgentContext, AgentSetupManifest, CommandOptions, CommandResult, McpServer, Sandbox, SandboxFile } from "../types.ts";
 
 /** 内存沙箱:runShell 记命令(可按命令包含的子串打脚本化输出),uploadFile / writeFiles 记内容。 */
 class FakeSandbox implements Partial<Sandbox> {
@@ -91,6 +91,32 @@ describe("codex installPlugins · 命令构造", () => {
     ]);
   });
 
+  it("marketplace.sparse 逐项生成 --sparse <path>(缺省不含由上面的精确命令断言覆盖);manifest 不记录 sparse", async () => {
+    const box = sb();
+    const out = await installPlugins(asSandbox(box), [
+      {
+        marketplace: {
+          name: "acme",
+          source: "acme/codex-plugins",
+          sparse: [".agents", "plugins/repo-map"],
+        },
+        name: "repo-map",
+      },
+    ]);
+    expect(box.commands[0]).toBe(
+      "codex plugin marketplace add 'acme/codex-plugins' --sparse '.agents' --sparse 'plugins/repo-map'",
+    );
+    expect(out[0]!.marketplace).toEqual({ name: "acme", source: "acme/codex-plugins" });
+  });
+
+  it("marketplace.sparse 空数组与缺省等价:add 命令不含 --sparse", async () => {
+    const box = sb();
+    await installPlugins(asSandbox(box), [
+      { marketplace: { name: "acme", source: "acme/codex-plugins", sparse: [] }, name: "repo-map" },
+    ]);
+    expect(box.commands[0]).toBe("codex plugin marketplace add 'acme/codex-plugins'");
+  });
+
   it("同名 marketplace 只连一次:两个 plugin 共用一个 marketplace.name → 只有一条 marketplace add,两条 plugin add", async () => {
     const box = sb();
     const plugins: CodexPluginSpec[] = [
@@ -339,3 +365,144 @@ describe("codexAgent · live step feedback", () => {
     expect(ctx.session.id).toBe("thread-1");
   });
 });
+
+describe("codexAgent · exec 信任姿态", () => {
+  // bug: memory/codex-hook-trust-headless-silent-skip.md
+  it("首轮与 resume 的 exec 命令都含 --dangerously-bypass-hook-trust(headless 下未授信 hook 被 codex 静默跳过,零报错)", async () => {
+    const stdout = JSON.stringify({ type: "thread.started", thread_id: "thread-1" }) + "\n";
+    const box = sb([{ match: "codex exec", result: () => ({ stdout }) }]);
+    const ctx: AgentContext = {
+      signal: new AbortController().signal,
+      flags: {},
+      sandbox: asSandbox(box),
+      session: createAgentSession(),
+      progress() {},
+      diagnostic() {},
+      log() {},
+    };
+    const agent = codexAgent({ apiKey: "test-key" });
+
+    await agent.send!({ text: "first" }, ctx);
+    await agent.send!({ text: "second" }, ctx);
+
+    const execs = box.commands.filter((c) => c.startsWith("codex exec"));
+    expect(execs).toHaveLength(2);
+    expect(execs[0]).not.toContain("codex exec resume");
+    expect(execs[1]).toContain("codex exec resume thread-1");
+    for (const cmd of execs) expect(cmd).toContain("--dangerously-bypass-hook-trust");
+  });
+});
+
+describe("codexAgent mcpServers · 形态落位", () => {
+  const ctx = { flags: {} } as AgentContext;
+
+  it("HTTP 形态:url 行 + [mcp_servers.<name>.http_headers] 子表;manifest 只记 name/url,headers 值不落盘", async () => {
+    const box = sb();
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [
+        { name: "team-memory", url: "https://mem.example.com/mcp/", headers: { Authorization: "Bearer sekret" } },
+      ],
+    }).setup!(asSandbox(box), ctx);
+
+    const mcp = box.commands.find((c) => c.includes("[mcp_servers.team-memory]"))!;
+    expect(mcp).toContain('url = "https://mem.example.com/mcp/"');
+    expect(mcp).toContain("[mcp_servers.team-memory.http_headers]");
+    expect(mcp).toContain('"Authorization" = "Bearer sekret"');
+    expect(mcp).not.toContain("command =");
+
+    const manifestRaw = box.written["__niceeval__/agent-setup.json"]!;
+    const manifest = JSON.parse(manifestRaw) as AgentSetupManifest;
+    expect(manifest.mcpServers).toEqual([{ name: "team-memory", url: "https://mem.example.com/mcp/" }]);
+    expect(manifestRaw).not.toContain("sekret");
+  });
+
+  it("边界:HTTP 形态无 headers → 不写空 http_headers 子表", async () => {
+    const box = sb();
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "team-memory", url: "https://mem.example.com/mcp/" }],
+    }).setup!(asSandbox(box), ctx);
+
+    const mcp = box.commands.find((c) => c.includes("[mcp_servers.team-memory]"))!;
+    expect(mcp).toContain('url = "https://mem.example.com/mcp/"');
+    expect(mcp).not.toContain("http_headers");
+  });
+
+  it("反例:同一 server 同时给出 command 与 url → setup 报错点名该 server,不写 MCP 块", async () => {
+    const box = sb();
+    // 形状判别不设 kind 标签,双字段的错误配置在类型上可能混得进来 —— 运行期兜底点名报错。
+    const dup = { name: "dup-server", command: "npx", url: "https://x.example.com/mcp" } as McpServer;
+    await expect(codexAgent({ apiKey: "k", mcpServers: [dup] }).setup!(asSandbox(box), ctx)).rejects.toThrow(
+      /dup-server/,
+    );
+    expect(box.commands.some((c) => c.includes("[mcp_servers."))).toBe(false);
+  });
+});
+
+describe("codexAgent postSetup · 安装后钩子", () => {
+  const mkCtx = (): AgentContext =>
+    ({
+      flags: {},
+      experimentId: "exp-1",
+      signal: new AbortController().signal,
+      progress: () => {},
+      diagnostic: () => {},
+    }) as unknown as AgentContext;
+
+  it("钩子在 Adapter 安装与 manifest 之后按数组顺序执行,拿到 SandboxHook 窄上下文", async () => {
+    const box = sb();
+    const seen: string[] = [];
+    let manifestPresentAtHook = false;
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "browser", command: "npx" }],
+      postSetup: [
+        async (sandbox, hookCtx) => {
+          manifestPresentAtHook = box.written["__niceeval__/agent-setup.json"] !== undefined;
+          seen.push(`a:${hookCtx.experimentId}`);
+          await sandbox.runShell("post-hook-a");
+        },
+        async (sandbox) => {
+          seen.push("b");
+          await sandbox.runShell("post-hook-b");
+        },
+      ],
+    }).setup!(asSandbox(box), mkCtx());
+
+    expect(seen).toEqual(["a:exp-1", "b"]);
+    expect(manifestPresentAtHook).toBe(true);
+    const configIdx = box.commands.findIndex((c) => c.includes("config.toml"));
+    const aIdx = box.commands.indexOf("post-hook-a");
+    const bIdx = box.commands.indexOf("post-hook-b");
+    expect(aIdx).toBeGreaterThan(configIdx);
+    expect(bIdx).toBeGreaterThan(aIdx);
+  });
+
+  it("钩子返回的 cleanup 合成一个闭包交还 runner,按 LIFO 执行", async () => {
+    const box = sb();
+    const order: string[] = [];
+    const cleanup = await codexAgent({
+      apiKey: "k",
+      postSetup: [() => () => void order.push("a"), () => () => void order.push("b")],
+    }).setup!(asSandbox(box), mkCtx());
+
+    expect(typeof cleanup).toBe("function");
+    await (cleanup as () => Promise<void> | void)();
+    expect(order).toEqual(["b", "a"]);
+  });
+
+  it("反例:钩子抛错从 setup 传播(attempt errored 通道)", async () => {
+    const box = sb();
+    await expect(
+      codexAgent({
+        apiKey: "k",
+        postSetup: [
+          () => {
+            throw new Error("hook boom");
+          },
+        ],
+      }).setup!(asSandbox(box), mkCtx()),
+    ).rejects.toThrow("hook boom");
+  });
+});

package/src/agents/codex.ts

@@ -19,7 +19,9 @@ import {
 import { mapCodexSpans } from "../o11y/otlp/mappers/codex.ts";
 import { t } from "../i18n/index.ts";
 import { DEFAULT_CODEX_CLI_VERSION } from "./coding-cli-versions.ts";
-import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from "../types.ts";
+import { assertMcpServers, isHttpMcp, mcpManifestEntries } from "./mcp.ts";
+import { runPostSetupHooks } from "./post-setup.ts";
+import type { Agent, AgentSetupManifest, McpServer, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
 // OpenAI Codex CLI 的 agent adapter(沙箱型)。
@@ -59,6 +61,12 @@ export interface CodexPluginSpec {
     source: string;
     /** 固定 Marketplace 的 Tag、Commit 或 Branch(→ `codex plugin marketplace add --ref`)。 */
     ref?: string;
+    /**
+     * sparse 拉取的路径列表,每项生成一个 `codex plugin marketplace add --sparse <path>`
+     * (codex 的 `--sparse` 必须带路径参数、可重复):大仓库只取插件所需路径,省略或空数组即全量 clone。
+     * 只影响拉取速度,不影响装出来的内容;manifest 不记录它。
+     */
+    sparse?: string[];
   };
   /** Marketplace 中的 Plugin 名。 */
   name: string;
@@ -71,7 +79,8 @@ export interface CodexConfig {
   baseUrl?: string;
   /**
    * 额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
-   * 格式对应 codex config.toml 的 [mcp_servers.<name>] 表。
+   * stdio 形态(command/args/env)写 [mcp_servers.<name>] 的 command 行;
+   * Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.<name>.http_headers] 子表。
    */
   mcpServers?: McpServer[];
   /**
@@ -92,6 +101,14 @@ export interface CodexConfig {
    * 项目相对路径与字节 SHA-256,不落正文。
    */
   configFile?: string;
+  /**
+   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
+   * 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+   * 「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
+   * 抛错按基础设施错误计(attempt errored)。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  postSetup?: SandboxHook[];
 }
 
 export function codexAgent(config?: CodexConfig): Agent {
@@ -155,15 +172,25 @@ export function codexAgent(config?: CodexConfig): Agent {
       }
 
       if (config?.mcpServers?.length) {
+        assertMcpServers(config.mcpServers);
         const mcpToml = config.mcpServers
           .map((s) => {
             // 注意是复数 mcp_servers:单数 [mcp_server.x] 会被 codex 静默忽略,
             // MCP 压根挂不上(实测 codex-cli 0.142.x,`codex mcp list` 可核对)。
-            const lines: string[] = [`[mcp_servers.${s.name}]`, `command = "${s.command}"`];
-            if (s.args?.length) lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
-            if (s.env && Object.keys(s.env).length) {
-              lines.push(`[mcp_servers.${s.name}.env]`);
-              for (const [k, v] of Object.entries(s.env)) lines.push(`${k} = "${v}"`);
+            const lines: string[] = [`[mcp_servers.${s.name}]`];
+            if (isHttpMcp(s)) {
+              lines.push(`url = "${s.url}"`);
+              if (s.headers && Object.keys(s.headers).length) {
+                lines.push(`[mcp_servers.${s.name}.http_headers]`);
+                for (const [k, v] of Object.entries(s.headers)) lines.push(`"${k}" = "${v}"`);
+              }
+            } else {
+              lines.push(`command = "${s.command}"`);
+              if (s.args?.length) lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
+              if (s.env && Object.keys(s.env).length) {
+                lines.push(`[mcp_servers.${s.name}.env]`);
+                for (const [k, v] of Object.entries(s.env)) lines.push(`${k} = "${v}"`);
+              }
             }
             return lines.join("\n");
           })
@@ -184,12 +211,8 @@ export function codexAgent(config?: CodexConfig): Agent {
         manifest.nativePlugins = await installPlugins(sb, config.plugins);
       }
       if (config?.mcpServers?.length) {
-        // manifest 只记「挂了哪个 server、怎么起」;env 里可能有 token,不落盘。
-        manifest.mcpServers = config.mcpServers.map((s) => ({
-          name: s.name,
-          command: s.command,
-          ...(s.args?.length ? { args: [...s.args] } : {}),
-        }));
+        // manifest 只记「挂了哪个 server、怎么连」;env / headers 里可能有 token,不落盘。
+        manifest.mcpServers = mcpManifestEntries(config.mcpServers);
       }
       if (nativeConfig) {
         // 只记来源路径与字节哈希,不落正文(任意官方配置都可能带敏感字符串)。
@@ -203,6 +226,10 @@ export function codexAgent(config?: CodexConfig): Agent {
       ) {
         await writeAgentSetupManifest(sb, manifest);
       }
+
+      // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
+      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
+      return await runPostSetupHooks(sb, ctx, config?.postSetup);
     },
 
     tracing: {
@@ -223,7 +250,12 @@ export function codexAgent(config?: CodexConfig): Agent {
 
     async send(input, ctx) {
       const sb = ctx.sandbox;
-      const flags = "--json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check";
+      // hook trust bypass 是 runtime-only(config.toml 设不了):headless 下 codex 对非 managed
+      // 来源 hook 的交互式授信永远无人应答,不带它插件装的 hook 会被静默跳过、零报错
+      // (见 memory/codex-hook-trust-headless-silent-skip.md)。沙箱内 hook 来源全部由实验配置
+      // 声明,与 approvals/sandbox bypass 同一信任层级。
+      const flags =
+        "--json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --dangerously-bypass-hook-trust";
       const prompt = shared.shellQuote(input.text);
       const resuming = ctx.session.id;
       const cmd = resuming
@@ -324,8 +356,12 @@ export async function installPlugins(
     const { marketplace } = plugin;
     if (!connected.has(marketplace.name)) {
       const refFlag = marketplace.ref ? ` --ref ${shared.shellQuote(marketplace.ref)}` : "";
+      // --sparse 只影响拉取速度,不影响装出来的内容;manifest 不记录它。
+      const sparseFlags = (marketplace.sparse ?? [])
+        .map((path) => ` --sparse ${shared.shellQuote(path)}`)
+        .join("");
       const add = await sb.runShell(
-        `codex plugin marketplace add ${shared.shellQuote(marketplace.source)}${refFlag}`,
+        `codex plugin marketplace add ${shared.shellQuote(marketplace.source)}${refFlag}${sparseFlags}`,
       );
       if (add.exitCode !== 0) {
         throw new Error(

package/src/agents/mcp.ts

@@ -0,0 +1,31 @@
+// MCP server 的形态判别与 manifest 映射 —— Claude Code / Codex 两个 adapter 共用。
+// 契约见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」:
+// stdio(command)与 Streamable HTTP(url)按形状判别;双字段是配置错误,setup 点名报错。
+
+import { t } from "../i18n/index.ts";
+import type { AgentSetupManifest, McpHttpServer, McpServer } from "./types.ts";
+
+/** 形态判别:有 url 的是 HTTP。调用前先过 {@link assertMcpServers}(双字段在那里报错)。 */
+export function isHttpMcp(server: McpServer): server is McpHttpServer {
+  return "url" in server && typeof server.url === "string";
+}
+
+/** 双字段(command + url)的配置错误在写任何沙箱配置前抛出,点名 server。 */
+export function assertMcpServers(servers: readonly McpServer[]): void {
+  for (const server of servers) {
+    if ("command" in server && "url" in server) {
+      throw new Error(t("mcp.ambiguousTransport", { name: server.name }));
+    }
+  }
+}
+
+/** manifest 条目:只记非 secret 字段(stdio 不含 env,HTTP 不含 headers)。 */
+export function mcpManifestEntries(
+  servers: readonly McpServer[],
+): NonNullable<AgentSetupManifest["mcpServers"]> {
+  return servers.map((s) =>
+    isHttpMcp(s)
+      ? { name: s.name, url: s.url }
+      : { name: s.name, command: s.command, ...(s.args?.length ? { args: [...s.args] } : {}) },
+  );
+}

package/src/agents/post-setup.ts

@@ -0,0 +1,33 @@
+// factory 的 postSetup 钩子执行器 —— Claude Code / Codex / Bub 共用。
+// 契约见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」:
+// 在 adapter 全部安装步骤(含 manifest)之后按数组顺序执行;复用 SandboxHook 的窄上下文;
+// 返回的 cleanup 合成一个 LIFO 闭包,由 runner 与 agent teardown 一起收尾;钩子抛错
+// 直接传播(attempt errored)。
+
+import type { Cleanup } from "../shared/types.ts";
+import type { Sandbox, SandboxHook, SandboxHookContext } from "../sandbox/types.ts";
+import type { AgentContext } from "./types.ts";
+
+export async function runPostSetupHooks(
+  sb: Sandbox,
+  ctx: AgentContext,
+  hooks: readonly SandboxHook[] | undefined,
+): Promise<Cleanup | void> {
+  if (!hooks?.length) return;
+  // 窄上下文与沙箱钩子同款:不把 session / model / telemetry 借给过程钩子。
+  const hookCtx: SandboxHookContext = {
+    experimentId: ctx.experimentId,
+    signal: ctx.signal,
+    progress: (update) => ctx.progress(update),
+    diagnostic: (input) => ctx.diagnostic(input),
+  };
+  const cleanups: Cleanup[] = [];
+  for (const hook of hooks) {
+    const cleanup = await hook(sb, hookCtx);
+    if (typeof cleanup === "function") cleanups.push(cleanup);
+  }
+  if (!cleanups.length) return;
+  return async () => {
+    for (const cleanup of [...cleanups].reverse()) await cleanup();
+  };
+}

package/src/agents/types.ts

@@ -7,21 +7,42 @@ import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 
 /**
- * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
- * 不是 native plugin 的一种。在 agent factory config 里声明,setup 阶段写进各自的配置文件。
- * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ * 本地 stdio 形态的 MCP server:沙箱内起子进程,按 stdio 说 MCP 协议。
+ * 与 {@link McpHttpServer} 按形状判别(有 `command` 的是 stdio,有 `url` 的是 HTTP)。
  */
-export interface McpServer {
+export interface McpStdioServer {
   /** 服务器唯一名(config key)。 */
   name: string;
   /** 启动命令(如 "npx"、"node"、"uvx")。 */
   command: string;
   /** 传给命令的参数。 */
   args?: string[];
-  /** 注入服务器进程的环境变量。 */
+  /** 注入服务器进程的环境变量(可能含 secret,不进 manifest)。 */
   env?: Record<string, string>;
 }
 
+/**
+ * 远程 Streamable HTTP 形态的 MCP server:沙箱直接连一个 HTTP 端点。
+ * `url` 必须沙箱内可达——宿主机上的服务先经隧道(cloudflared / tailscale 等)暴露。
+ */
+export interface McpHttpServer {
+  /** 服务器唯一名(config key)。 */
+  name: string;
+  /** Streamable HTTP 端点(如 https://mem.example.com/mcp/)。 */
+  url: string;
+  /** 逐字写进每个请求的 HTTP 头(常用于 Authorization;可能含 secret,不进 manifest)。 */
+  headers?: Record<string, string>;
+}
+
+/**
+ * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
+ * 不是 native plugin 的一种。stdio 与 Streamable HTTP 两种形态按形状判别,不设 kind 标签
+ * (两种形态各有唯一必填判别字段);同时给出 `command` 与 `url` 属配置错误,setup 报错点名。
+ * 在 agent factory config 里声明,setup 阶段写进各自的配置文件。
+ * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ */
+export type McpServer = McpStdioServer | McpHttpServer;
+
 /**
  * Skill 的来源描述 —— Claude Code / Codex / Bub 共用的**数据类型**:只统一「从哪里取得
  * 哪份 Skill」,安装位置、发现机制、要不要额外写 project instruction 由各 Adapter 决定。
@@ -67,8 +88,8 @@ export interface AgentSetupManifest {
     /** 安装后 CLI 报告的版本;取不到时省略。 */
     resolvedVersion?: string;
   }>;
-  /** 挂上的 MCP server(不含 env:secret 不进 manifest)。 */
-  mcpServers?: Array<{ name: string; command: string; args?: string[] }>;
+  /** 挂上的 MCP server(只记非 secret 字段:stdio 不含 env,HTTP 不含 headers)。 */
+  mcpServers?: Array<{ name: string; command: string; args?: string[] } | { name: string; url: string }>;
   /**
    * 官方原生配置文件(Claude Code `settings.json` / Codex `config.toml`):只记 Agent 名、
    * 项目相对来源路径与原始字节的 SHA-256,不落正文 —— 任意官方配置都可能携带敏感字符串,

package/src/cli.ts

@@ -17,7 +17,7 @@ import { planCarry } from "./runner/fingerprint.ts";
 import { failureDetailFromResult } from "./runner/feedback/failure.ts";
 import { stopAllSandboxes, liveSandboxCount } from "./sandbox/registry.ts";
 import { evalLevelStats } from "./shared/verdict.ts";
-import { sandboxRecommendedConcurrency } from "./sandbox/resolve.ts";
+import { prepareRunSandboxes, resolvedSandboxRecommendedConcurrency } from "./runner/sandbox-selection.ts";
 import { Json, JUnit } from "./runner/reporters/json.ts";
 import { Artifacts as ArtifactsReporter } from "./runner/reporters/artifacts.ts";
 import {
@@ -170,15 +170,15 @@ const FLAG_OPTIONS = {
   diff: { type: "boolean" },
   /** `show` 命令专用:执行时间轴——对匹配的每个 experiment × eval 分节,逐 attempt 列时间 / verdict / 摘要 / 耗时 / 成本 / locator;与 `--report` 互斥。 */
   history: { type: "boolean" },
-  /** `show` / `view` 命令专用:按路径段前缀收窄 experiment;组名会选中组内全部配置。 */
-  experiment: { type: "string" },
+  /** `show` / `view` 命令专用:按路径段前缀收窄 experiment(与 `niceeval exp` 位置参数同一套匹配);组名会选中组内全部配置。`view --out` 时同一收窄决定出站内容。 */
+  exp: { type: "string" },
   /** `show` / `view` / `sandbox enter|list|stop` 共用:结果根目录(`.niceeval` 之外的另一个根,如 `copySnapshots` 产出的发布根)。 */
   results: { type: "string" },
   /** `view` 命令专用:只打开这一份快照文件(`snapshot.json`);文件不可读时命令失败(扫描模式只跳过)。 */
   snapshot: { type: "string" },
   /** `show` / `view` 命令专用:用文件默认导出的 `defineReport(...)` 替换两者共用的默认报告。 */
   report: { type: "string" },
-  /** `show` / `view` 命令专用:选择多页报告的页(页 id 见 `show --report` 的页索引);`view` 里定初始页。 */
+  /** `show` / `view` 命令专用:选择报告的初始页;`show` 渲染该页并在尾部附其余页索引,`view` 以它作初始路由。未命中的页 id 按用法错误退出并列出可用页 id。 */
   page: { type: "string" },
   /** 只打印本次会匹配到的 eval × 运行配置,不实际执行(按下面 `--output` 选中的 profile 给出预览)。 */
   dry: { type: "boolean" },
@@ -308,7 +308,7 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
     sandboxPath: values.path as string | undefined,
     leaveRunning: values["leave-running"] === true,
     history: values.history === true,
-    experiment: values.experiment as string | undefined,
+    experiment: values.exp as string | undefined,
     results: values.results as string | undefined,
     snapshot: values.snapshot as string | undefined,
     report: values.report as string | undefined,
@@ -320,7 +320,7 @@ function parseArgs(argv: string[]): { command: string; positionals: string[]; fl
 /**
  * exp 只接受两类输入:位置参数选「跑哪些 eval」+ 调度/输出/机器出口 flag 选「对着哪个 agent、
  * 怎么跑」。show / view 专属的证据切面(`--source`/`--execution`/`--diff`)、时间轴(`--history`)、
- * Scope 收窄(`--experiment`/`--results`)、报告装载(`--report`/`--page`)、查看器
+ * Scope 收窄(`--exp`/`--results`)、报告装载(`--report`/`--page`)、查看器
  * (`--snapshot`/`--out`/`--port`/`--open`)不能被 exp 静默忽略(见 docs/feature/experiments/
  * cli.md「用法错误」)。返回第一个被误用的 flag 及其归属命令(用于报错),没有误用返回 undefined。
  */
@@ -333,7 +333,7 @@ function firstViewerOnlyFlag(flags: Flags): { flag: string; command: string } |
   if (flags.timing !== undefined) return { flag: "--timing", command: SHOW };
   if (flags.diff || flags.diffPath !== undefined) return { flag: "--diff", command: SHOW };
   if (flags.history) return { flag: "--history", command: SHOW };
-  if (flags.experiment !== undefined) return { flag: "--experiment", command: BOTH };
+  if (flags.experiment !== undefined) return { flag: "--exp", command: BOTH };
   if (flags.results !== undefined) return { flag: "--results", command: BOTH };
   if (flags.report !== undefined) return { flag: "--report", command: BOTH };
   if (flags.page !== undefined) return { flag: "--page", command: BOTH };
@@ -468,7 +468,7 @@ function evalsFilterFromExperiment(
 ): (id: string) => boolean {
   const patternFilter = makeFilter(patterns);
   let expFilter: (id: string) => boolean = () => true;
-  if (Array.isArray(evals)) expFilter = (id) => evals.includes(id) || evals.some((e) => id.startsWith(e + "/"));
+  if (Array.isArray(evals)) expFilter = makeFilter(evals);
   else if (typeof evals === "function") expFilter = evals;
   return (id) => expFilter(id) && patternFilter(id);
 }
@@ -566,11 +566,10 @@ async function main(): Promise<void> {
   }
 
   if (command === "view") {
-    // 位置参数只有一种含义:eval id 前缀(收窄报告槽 Scope)。结果根经 --results 递入,
+    // 位置参数只有一种含义:eval id 前缀(收窄有效根)。结果根经 --results 递入,
     // 单开一份快照经 --snapshot 递入;--report 整槽替换报告槽(与 show --report 吃同一个文件),
     // --page 定初始页。文件与目录都不进位置参数(docs/feature/reports/view.md「打开与收窄」)。
-    // --out 与位置参数 / --experiment 的互斥在 buildView 内校验(单点,报错文案含 copySnapshots
-    // + filter 的下一步),经 exitOnViewUserError 按用法错误退出。
+    // --out 接受同一收窄:出站内容即收窄后的有效根(docs/feature/reports/view.md「静态导出」)。
     let viewInput: { input?: string; patterns: string[] };
     try {
       viewInput = resolveViewInput(cwd, positionals, {
@@ -771,6 +770,9 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
+  // environments 查表在 dry-run 与真实运行共用的规划边界完成；缺表项在任何沙箱/agent 花费前穷举失败。
+  prepareRunSandboxes(evals, agentRuns, config.sandbox);
+
   if (flags.dry) {
     // --dry 只按所选 profile 打印计划,不运行、不落盘 —— 三种 profile 各自的展示逻辑
     // 都在 runner/feedback/{human,agent,ci}.ts 里,这里只负责拼数据、选函数、写流、退出。
@@ -826,7 +828,7 @@ async function main(): Promise<void> {
   // envelope 展示的"携入"就会和 run.ts 真实调度的"携入"对不上(见 memory 的
   // live-carry-row-shows-waiting-forever)。
   const priorResults = flags.force ? undefined : await loadLatestResultsPerEval(join(cwd, ".niceeval"));
-  const carryPlan = priorResults?.length ? await planCarry(evals, agentRuns, priorResults) : undefined;
+  const carryPlan = priorResults?.length ? await planCarry(evals, agentRuns, priorResults, config.sandbox) : undefined;
   const reusedFailures = (carryPlan?.carriedResults ?? [])
     .map(failureDetailFromResult)
     .filter((failure) => failure !== undefined);
@@ -834,8 +836,7 @@ async function main(): Promise<void> {
   // 无全局默认:并发上限由 sandbox provider 的推荐值决定(多个 agentRun 各有 sandbox 时取
   // 最小值,最保守的 provider 决定上限)。同一个值既进 RunFeedbackPlan.shape,也传给 runEvals——
   // 两处必须是同一个数字,dashboard 展示的并发上限不能和真实调度的并发上限对不上。
-  const sandboxRecs = agentRuns.map((r) => sandboxRecommendedConcurrency(r.sandbox));
-  const sandboxDefaultConcurrency = sandboxRecs.length > 0 ? Math.min(...sandboxRecs) : 10;
+  const sandboxDefaultConcurrency = resolvedSandboxRecommendedConcurrency(evals, agentRuns, config.sandbox);
   const maxConcurrency =
     flags.maxConcurrency ??
     envNumber("NICEEVAL_MAX_CONCURRENCY") ??

package/src/define.ts

@@ -55,6 +55,9 @@ export function defineEval(def: EvalDef): EvalDef {
   if (typeof def.test !== "function") {
     throw new Error(t("define.evalTestRequired"));
   }
+  if (def.environment !== undefined && def.environment.trim().length === 0) {
+    throw new Error(t("define.evalEnvironmentEmpty"));
+  }
   return def;
 }
 

package/src/i18n/en.ts

@@ -24,6 +24,8 @@ export const en = {
   "skill.repoAmbiguous": "Repo skill {{source}} contains multiple skills; select which ones to enable with `skills: [...]`. Available: {{available}}.",
   "skill.repoUnknownSkill": "Repo skill {{source}} (ref: {{ref}}) has no skill named \"{{skill}}\". Available: {{available}}.",
   "skill.copyFailed": "Could not install skill \"{{name}}\" into {{dest}}:\n{{tail}}",
+  "mcp.ambiguousTransport":
+    "MCP server \"{{name}}\" specifies both \"command\" and \"url\" — pick one transport: \"command\" for a local stdio server, \"url\" for a remote Streamable HTTP endpoint.",
   "plugin.marketplaceFailed": "Could not connect {{agent}} marketplace \"{{name}}\" (source: {{source}}, ref: {{ref}}):\n{{tail}}",
   "plugin.marketplaceVerifyFailed": "Could not read back the registered marketplace list after adding {{agent}} marketplace \"{{name}}\" ({{command}}):\n{{tail}}",
   "plugin.marketplaceNameMismatch":
@@ -82,15 +84,15 @@ export const en = {
     "      --timing      unified timing tree for the attempt (phases + hooks/commands/turns + per-turn OTel)\n" +
     "      --diff[=file] sandbox workspace file-change summary; =file expands one file\n" +
     "      --history   per experiment × eval execution timeline (mutually exclusive with --report)\n" +
-    "      --results <dir>   pin a results root    --experiment <id>   one experiment\n" +
-    "      --report <file>   custom report    --page <id>   pick a page (multi-page\n" +
-    "        reports print a page index with copyable commands)\n" +
+    "      --results <dir>   pin a results root    --exp <id>   one experiment\n" +
+    "      --report <file>   custom report    --page <id>   pick the initial page (multi-page\n" +
+    "        reports render it, then list the rest as a page index with copyable commands)\n" +
     "  niceeval list                                       list discovered evals\n" +
     "  niceeval view [eval-id-prefix…] [--out dir] [--port n] [--no-open]\n" +
     "      report pages + evidence rooms; --report <file> swaps in your report\n" +
     "      (same file as show); --page <id> picks the initial page;\n" +
     "      --results <dir> pins a results root; --snapshot <file> opens exactly\n" +
-    "      one snapshot; --experiment <id> one experiment\n" +
+    "      one snapshot; --exp <id> one experiment\n" +
     "      --out <dir> exports a static site: index.html plus the viewer\n" +
     "      artifacts, ready for any static host\n" +
     "  niceeval sandbox list|enter|history|diff|stop  inspect & destroy sandboxes kept by --keep-sandbox\n" +
@@ -107,7 +109,7 @@ export const en = {
   "cli.show.noResults": "No results found under {{root}}. Run `niceeval exp` first, then `niceeval show`.\n",
   "cli.show.runDirMissing": "Results directory not found: {{dir}}\n",
   "cli.show.noEvalMatch": "No results matched: {{patterns}}. Evals with results: {{evals}}\n",
-  "cli.show.noExperimentMatch": "No experiment matched --experiment {{arg}}. Experiments with results: {{experiments}}\n",
+  "cli.show.noExperimentMatch": "No experiment matched --exp {{arg}}. Experiments with results: {{experiments}}\n",
   "cli.show.historyReportConflict":
     "`--history` and `--report` are mutually exclusive: both take over the main output. --history is the host's per-attempt execution timeline; for snapshot-level trends, compose exp.snapshots inside your report file instead.\n",
   "cli.show.evidenceNeedsEval":
@@ -151,6 +153,7 @@ export const en = {
   "context.turnFailedDefault": "This send returned failed (turn status = failed)",
   "define.agentNameRequired": "defineAgent requires name.",
   "define.evalIdRejected": "defineEval does not accept id; ids are derived from file paths.",
+  "define.evalEnvironmentEmpty": "defineEval environment must be a non-empty profile id when provided.",
   "define.evalTestRequired": "defineEval requires an async test(t) function.",
   "define.experimentAgentRequired": "defineExperiment requires agent.",
   "define.experimentFlagNotJson": "experiment.flags.{{key}} is not JSON-serializable (functions / undefined / cycles / bigint are not allowed); flags are persisted verbatim into result snapshots and must be plain JSON.",