agentcompass run 和 agentcompass launch 使用同一组运行控制来管理调度、容错和评测产物。execution.task_concurrency 是实际 attempt 执行唯一的并发设置，不会再区分任务并发与 attempt 并发两个参数。
本页说明各项控制的作用和使用建议。配置文件的写法与覆盖顺序见 agentcompass config，完整的单请求参数签名见 agentcompass run，多请求编排及其 CLI 覆盖见 agentcompass launch。
安全扩展并发
这里的 provider 是创建和管理 Environment 的执行后端，例如 Docker、Daytona 或 Modal。
有效 attempt 并发受
task_concurrency 和当前 provider 限制中较小者约束；env-open-qps 只控制 Environment 的启动节奏。使用 strategy: avg 时，同一任务的多次 attempt 共享该并发池，且只有 Benchmark 和 Harness 都声明状态隔离时才会重叠执行，否则保持串行。model 端点容量、provider 配额以及本地 CPU 和内存还可能进一步降低实际并发。单个 sandbox 的 CPU 和内存限制属于 Environment 参数，区别见理解作用范围。
CLI 写法
CLI 中可为不同 provider 重复传入后两项。多个评测请求使用不同 Environment 时，可以统一限制各 provider 的容量：agentcompass run 只需为该请求实际使用的 provider 设置限制。
配置文件写法
在--config 配置文件中，provider 限制使用映射表示，不重复书写 YAML 键：
launch 编排文件将共享的 task_concurrency 放在顶层，provider 映射仍放在 runtime 下，详见 agentcompass launch。
调整并发时，先选择少量有代表性的 Benchmark 任务，将任务并发设为 1 完成验证，再以 2 或 4 逐步增加。观察 Environment 启动延迟、model 延迟、错误率和内存用量；错误开始增多时，回退到最后一个稳定值。
设置合适的超时
使用--timeout-seconds 限制整个运行，通过 --execution-params 设置各个任务阶段的预算。Environment 启动、单条命令和单次模型请求还可有自己的时限；多个限制重叠时，先到的时限生效。
整体时限与组件时限
| 层级 | 参数位置 | 控制范围 |
|---|---|---|
| 评测总时限 | CLI：—timeout-seconds <秒数> | 一次 run 中的全部任务共享该时限；一次 launch 中的全部请求也共享该时限。计时从组件预检完成后开始，覆盖任务加载、准备、执行、分析和汇总。到期后取消未完成工作并进入资源清理。默认值为 360000 秒（100 小时）。显式设置为 0 时不设置评测总时限；这不会影响下面的组件专属超时。 |
| Environment 创建 | JSON 字段：setup.build_timeout_seconds通过 --env-params 传入 | 适用于 Daytona、Modal 等提供该字段的 Environment。每次创建 sandbox 都单独计时；超时只会使本次创建失败，不限制已创建 sandbox 中的后续操作。 |
| Harness 专属 | JSON 字段：由 Harness 定义 通过 --harness-params 传入 | 控制范围由具体字段决定。command_timeout 限制单条命令，request_timeout 限制单次服务请求。任务阶段 deadline 使用公共 execution 字段。 |
| Benchmark 专属 | JSON 字段：由 Benchmark 定义 通过 --benchmark-params 传入 | 控制范围由具体字段决定。例如，PinchBench 的 judge_timeout_seconds 限制单次评委 model 请求。 |
每个任务的阶段 deadline
通过run --execution-params、YAML 的 execution 或 SDK 的 execution_params 设置阶段超时。使用 launch 时，配置放在 defaults.execution 或 requests[].execution 下。
下图展示包含 Harness 和独立评测环境的单次 attempt 的阶段预算，不表示任务整个生命周期的总时限。阶段按从左到右的顺序执行，列宽不代表实际耗时。部分阶段可能跳过；下载和恢复是否执行，取决于评测模式及产物配置。
时间预算单位均为秒。执行预算包括
execute_task() 内部的准备操作、模型请求和工具执行。调用之前的环境／session 初始化，以及调用之后的结果收集，分别计时。评测预算从评测环境就绪、产物恢复完成后开始计时。
执行和评测的覆盖值未填写或为 null 时，依次继承 Benchmark 计划默认值、task 默认值；执行阶段还可回退到 Harness 默认值。所有来源均未提供预算时，该阶段不设时限。
最终预算为 基础秒数 × 有效倍率。设置阶段专属倍率时，它替换 timeout_multiplier；为 null 时使用公共倍率，两者不会相乘。倍率只影响执行和评测；结果收集、产物准备、下载和恢复仍使用各自的预算。没有基础预算时，倍率也不会产生时限。
--timeout-seconds 总时限。
收集输出并构建 RunResult
harness_result_timeout_seconds 限制 Harness 在执行成功、报错或超时后进行的 collect_result() 调用。它读取日志、已保存状态和提交文件，提取答案，将轨迹、状态及诊断信息整理为 RunResult，供持久化、分析和评测使用。部分 Harness 还会在此阶段写出轨迹文件。
结果收集可能在执行结束后继续进行 sandbox 文件读写，因此使用独立预算；它不运行 agent，也不发起新的模型请求。收集完成后关闭 Harness session，再在仍可用的任务 sandbox 中准备和下载产物。无 Harness 的 Benchmark 跳过此钩子；收集失败会与原始执行错误一并记录。
产物准备与传输
准备命令按序执行，同时受两层限制：整组共享artifact_collect_timeout_seconds，每条命令有自己的 timeout_seconds，先到的时限生效。例如三条命令各限 60 秒、整组限 100 秒时，单条最多使用 60 秒，整组合计最多使用 100 秒。整组预算为 null 时，只保留单条命令限制。
一次整批下载中的所有声明文件共享 artifact_limits.timeout_seconds；后续恢复使用相同预算重新计时。按默认值，一次下载最多使用 600 秒，恢复另有 600 秒。
配置运行后预算
以下 YAML 为构建RunResult 分配 120 秒、整组准备分配 100 秒、每次整批传输分配 1,800 秒，同时继承声明路径、命令及单条命令限制：
null：
--execution-params 中的对应字段。SDK 的 build_run_request()、run_evaluation() 和 async_run_evaluation() 均接受 execution_params。
根据超时位置选择参数
配置产物
通过execution 配置需要保存的产物、准备方式，以及评测时是否恢复产物。准备和传输时限见超时设置。
保存与恢复产物
对于已启用产物收集且有声明路径的 Benchmark，评测模式决定传输行为：save_artifacts 未填写或为 null 时使用对应模式的默认值。跳过的传输不消耗传输预算；关闭下载后，已声明的准备命令和 Harness 结果收集仍会执行。保存产物只保留本地文件，需要保留 sandbox 时使用 keep_environment。
每次采集或恢复的产物大小／数量默认限制为 16 GiB 和 100,000 个条目，可通过 artifact_limits 下的 max_mb、max_files 调整。max_mb 限制整个产物列表的累计大小，也限制每个传输归档（含归档开销）；1 MB 按 1,048,576 字节计算。
准备或传输失败会保留已校验文件及执行诊断，但跳过该次 attempt 的评分和可续跑 checkpoint 创建。进度记录提供操作名称、已完成字节及剩余预算。
覆盖产物路径和准备命令
Benchmark 声明提供默认路径和命令。在execution 下可分别覆盖：
替换列表中应包含仍需保留的原始路径或命令。这些覆盖要求 Benchmark 支持产物收集，详见提交产物与回放。
source 使用 sandbox 内的绝对路径，destination 使用本地相对路径。命令在 Environment 默认 workdir 中执行；依赖任务 workspace 时，使用绝对路径或显式 cd。
/app/submission 保存到该 attempt 的本地 artifacts/submission/，排除 *.tmp；/app/result.json 保存为 artifacts/result.json。源路径不存在时记录缺失，不会使收集失败。独立环境评测会将文件恢复到原始 source 路径。
只重试瞬时失败
--max-retries 设置每个逻辑 attempt 内的最大 retry 次数。例如，--max-retries 2 表示该 attempt 初始执行失败后最多再替换执行两次；retry 不会增加新的指标 attempt。
--retry-pattern-list 分别匹配每条 ERROR 的 message 和 code；null 和 [] 都只重试 FATAL。FATAL 有共享预算必重试，WARNING 不触发重试。
只对再次执行可能恢复的临时错误启用重试，例如网络连接中断、临时服务异常或 sandbox 超时：
retry_count 和 retry_counts 记录次数，被丢弃的执行保存在 retry_details/ 供诊断。
输出与复用
命名新运行
对于agentcompass run，三个参数分别对应结果路径的不同层级：
--results-dir设置结果根目录，默认为results。--run-name添加可选的实验分组目录。--run-id设置本次运行的目录名；不指定时使用当前时间戳。
agentcompass launch 则使用每个请求规范化后的 name 代替这个组合目录名：
agentcompass launch。
下面的命令使用 ablation 区分实验组，并将本次运行固定命名为 baseline：
继续中断的运行
--reuse 用于基于已有运行继续评测。AgentCompass 按任务 ID 复用完整、兼容且不含错误的详情，也可以为未完成的多次尝试任务恢复有效的终态 attempt checkpoint：
--reuse 会选择以下层级中的最新运行：
run 只会在相同结果根目录、可选 run-name 前缀及 Model/Benchmark/Harness 组合目录中查找；launch 则在按请求名称划分的输出命名空间中查找。已有目录保持原样，自动复用不会搜索旧 Benchmark/Model 目录层级。
来源运行必须使用受支持的运行 schema、相同的 Benchmark ID 和 attempt 计划。可复用数据按 task ID 与 attempt 序号匹配，不要求请求参数和任务输入完全一致。继续待执行的 fresh 评测时，可以修改评测超时、资源或环境变量。新运行记录来源，并保留复用的详情或 checkpoint；详见复用校验。
复用按逻辑 attempt 使用当前任务计划判断。完整的 WARNING 结果、当前 pattern 未命中的 ERROR 结果可复用；FATAL 或命中的 ERROR 按当前重试政策处理，使用新 run 的共享预算，历史次数不扣减新预算。零预算不会把失败改成成功。只有评分输入完整的 none/fresh 评测失败可恢复评分；reuse 模式重新执行整个 attempt。
从已保存产物继续评测
推理和必要收集完成且无 FATAL 后，none/fresh 保存 v4 checkpoint，包含已分类推理与输入快照、身份、来源、网络策略和产物完整性。允许具有完整输入的 ERROR 结果恢复；fresh 恢复产物，none 校验声明的本地输入路径与摘要。传输不完整或包含不可序列化运行对象时不恢复。
新 run 复制已校验的 checkpoint 和采集产物。恢复时校验 task/attempt 身份、来源兼容性、网络策略与输入完整性，使用当前计划及保存输入的新副本。driver 文件依赖必须仍存在且摘要一致；恢复不重建运行中的进程或旧 sandbox。
要关闭待执行任务的自动 checkpoint 恢复，在
agentcompass run 中添加 --no-checkpoint-resume，在 Python SDK 中传入 checkpoint_resume=False，或配置：
defaults.runtime.checkpoint_resume 或 requests[].runtime.checkpoint_resume，有效默认值为 true。此选项不会强制重新评测已完成结果，不会关闭终态 attempt 的调度 checkpoint，也不会阻止保存新的 checkpoint。
保留 Environment 以便调试
当失败需要直接检查任务或验证器 sandbox 时，添加--keep-environment：
日志与进度
--progress 只控制终端显示；无论选择哪种模式，AgentCompass 都会照常保存进度、日志和任务结果。保存位置见结果。
环境变量作用域
所有变量作用域统一通过--env-params 配置（SDK 使用 environment_params，YAML 放在 environments 下所选 provider 中）。env_variables 提供公共启动/命令变量，run_env_variables 用于 agent 安装/执行，evaluation_env_variables 用于评测命令。evaluation_environment_env_variables 独立覆盖 fresh verifier 启动变量，要求 fresh 模式；旧 Harness env 输入会报错。
execution.download_artifacts 配置项已替换为 execution.save_artifacts；旧配置键会被拒绝。
错误处理与计分有效性
RunResult.issues 是唯一的执行错误契约。每条问题包含 severity（fatal、error、warning）、phase（setup、run、collect、evaluate、cleanup）、稳定的 code 和脱敏 message。RunResult.error 已移除；完整脱敏 traceback 与异常链保存在 artifacts.execution_diagnostics。
FATAL 表示准备、Environment、外部工具服务、模型鉴权／配额／服务端或 Judge 故障。Judge 超时、无效 JSON 和缺少必需评分字段同样是 FATAL。模型 API 或 Harness 超时、模型无有效输出属于 ERROR。模型交付缺失、普通 verifier reward 文件缺失或解析失败、清理失败属于 WARNING；已有明确受信准备失败证据时，即使没有 reward 仍保留 FATAL。
ERROR 不覆盖 Benchmark 的有效得分。普通 verifier reward 异常仍按有效 fail／0 观察处理；上述 Judge 协议错误是 FATAL 例外。runtime 不会仅根据 status 为缺失观察补零。
execution.max_retries 默认 0，是每个逻辑 attempt 各阶段共享的额外重试预算。FATAL 有预算必重试；ERROR 仅在配置的正则匹配其 message 或 code 时重试；WARNING 不触发重试。null 和 [] 均表示只重试 FATAL。需要容忍瞬时服务故障时可设 execution.max_retries=2；零预算下，一次未解决的 FATAL 就会使 run 失败。pattern 不再匹配完整 traceback、拼接的多条 issue 或脱敏凭证，旧配置应迁移到稳定 code 或保留的诊断特征。
预算与 pattern 均取自当前任务解析后的 plan。none 和 fresh 只重试评测，并使用隔离的推理快照；fresh 每轮新建评测 Environment。reuse 重跑整个 attempt。跨 run 恢复使用新预算，旧次数只保留为历史。重试已解决的问题留在历史中，不进入最终 issues。
任一逻辑 attempt 最终仍有 FATAL，该题所有指标失效，即使另一个 attempt 成功也不能计分。MetricReport.evaluation_failed 为 true，所有正式 value 为 null，可用值写入明确标注的 reference_value。参考分从分子、分母和权重中排除整道失效题；没有有效题时两者都为 null。run 状态为 failed，CLI 非零退出，SDK 失败消息包含结果路径；编排中的其他请求继续执行。
计数满足 evaluated + unavailable + invalidated = total；error 是独立诊断计数。attempt coverage 对包含最终 ERROR／FATAL 的逻辑 attempt 去重计数，WARNING 和已解决的重试历史不计入。合法 pass@k 提前停止不算缺失 attempt。
当前 task 和 run-info schema 为 v3，evaluation checkpoint 为 v4，保存已分类的推理与准备输入快照、网络策略和产物完整性信息。旧 v2 结果只在读取边界依据可靠结构化证据转换；仅自由文本的旧失败保持历史分类未知，进入新计分前需重新执行，仍可作为历史结果浏览。旧 checkpoint 缺少已分类快照时，跨 run 复制会给出原因并恢复正常执行。新格式缺少 issues 或仍有结果级 error 都是格式错误。