运行时实验开关（“levers”）

OpenSquilla 提供了一组 opt-in 的运行时行为，脚本化或由 harness 控制的运行可以在不修改代码或配置文件的情况下按次启用它们。本页记录这些开关必须遵循的约定，以及调用方 harness 如何验证其请求的开关确实被送达。配套工具位于 scripts/experiments/。

约定

• 命名：OPENSQUILLA_<AREA>_<KNOB>（例如 OPENSQUILLA_PROVIDER_HISTORY_DEDUP、 OPENSQUILLA_TOOL_REPEAT_NUDGE_THRESHOLD）。
• 单一解析位置：环境变量的值仅在 engine/turn_runner/agent_bootstrap_stage.py（_*_from_env 辅助函数）中解析，流入 AgentConfig 字段，并由运行时解析器消费。引擎中的其他任何部分都不会直接读取这些变量。
• 默认关闭：不设置任何开关时，运行时的行为与原生 OpenSquilla 一致。开关绝不能改变未设置它的用户的行为。
• 严格取值：无法识别的值会抛出异常，而不是被静默忽略，这样运行清单就不会记录一个该次运行实际并未应用的覆盖。
• Provider 差异放在策略表中：逐 provider 的行为应放在 OpenAICompatPolicy、ProviderContextProfile 或 reasoning_dialects 字段中——绝不能放在调用点上以模型名为条件的判断里。

送达验证

设置了开关的 harness 可以端到端地验证送达：

1. harness 的允许列表决定哪些变量会被传入容器（docker exec -e ...）。
2. harness 会把送达的环境回显到该次运行的 metadata.json 中的 agent.controls.progress_watchdog_env 下。这一回显由 harness 适配器无条件写入——它不依赖任何运行时开关，包括 watchdog 模式本身。
3. scripts/experiments/exp_finalize.py 以预期的环境（AGENT_ENV_DELIVERY_VARS）作为已完成运行的门禁，而 scripts/experiments/check_treatment_delivery.py 会断言最终的 provider payload 形态（例如预期的 proof 预算、reasoning effort，以及有上界的 reasoning 回退次数）。

添加新开关

新开关必须：

1. 被加入调用方 harness 的允许列表，
2. 默认关闭，并且
3. 如果它可能影响任务结果，则加入 AGENT_ENV_DELIVERY_VARS，使送达门禁覆盖它。

复现旧行为

有两个默认值在这段代码合并时被翻转为关闭；希望获得先前行为的运行应显式固定它们：

• OPENSQUILLA_PROGRESS_WATCHDOG_MODE=warn_model（合并后的默认值：off； 其他取值：log、block）。由 harness 控制的运行应始终显式固定此模式，而不是依赖默认值。
• OPENSQUILLA_TOOL_REPEAT_NUDGE_THRESHOLD=3（合并后的默认值：0，即禁用）。