Docs: binary resolution, cancellation, progress cap, phase-1 deviations

- runbook: how executor binaries are resolved (bins or PATH) and what that
  assumes on oregon (no codex installed) and win10; cancellation and
  max_progress_rounds in the item lifecycle; secrets scrubbed from children.
- design: blocked-by ordering is a TODO (not read by the scheduler); failure
  classification, success-when-tagged, one-time immediate rebuild, retries
  outside the thread-round budget, ID-based new-comment filter.
- executor contract: how core reads ExecResult, kill used for cancel, Windows
  quoting assumptions, codex exec resume without -C/-s.

docs/executor-contract.md

@@ -15,7 +15,13 @@ agentd 不常驻：一轮运行比起它的那次 tick 活得久，所以执行
 `Run(run_id, repo, prompt, model, effort, tier, thread_id, script)`：`thread_id` 非空即续该线程。
 `ExecResult(last_message, exit_code, thread_id, log_paths, tail)`：`last_message` 原样回帖，首行应为 `[review]/[question]/[blocked]/[progress]`；`thread_id` 供下一轮续接；`tail` 是失败说明里的"最后一帧"（stderr 尾部/最后事件）。
 
-执行器**不接触 Plane**：不持有 token、不改工作项。回帖、状态流转、重试、超时、线程重建都由 core 统一处理。
+执行器**不接触 Plane**：不持有 token、不改工作项。回帖、状态流转、重试、超时、线程重建都由 core 统一处理。transport 启动 runner/中继脚本时传入去掉所有 `token_key`/`webhook_secret_key` 变量的环境（`Config.scrubbed_env()`）；新 transport 必须同样处理。
+
+## core 如何解读 `ExecResult`
+- 成功 = 最后消息首行带合法标签（**不看退出码**），或无标签但退出码 0（按 review 处理并注明）。首行判定跳过空行、BOM、开头的 ```/~~~ 代码围栏行和 `---` 分隔线，容忍 `**`、`>`、`#`、反引号等修饰，标签后可跟任意文字（`[progress] 第 2 步`）。
+- 失败分类：`tail` 决定是否临时性（`retry.transient_patterns`），`tail` + `last_message` 决定 env（`retry.env_patterns`）。所以适配器应把 stderr 尾部/最后一个事件放进 `tail`，不要把 agent 正文塞进去。
+- 续线程（`thread_id` 非空）的一轮非临时性失败 → core 立即在新线程重跑一次（附交接摘要），只一次。
+- `kill(handle)` 既用于超时，也用于取消（工作项在运行中被移出 In Progress）；必须能在运行未结束时调用。取消后 core 会尝试 `collect(handle)` 取线程 ID，所以 `collect` 在未结束的运行上也不能抛出致命错误（抛异常会被忽略）。
 
 ## RunnerExecutor（现有三个适配器的共同形态）
 1. 在终端上建运行目录 `<run_root>/<run_id>`（清空旧文件），写 `prompt.md`。
@@ -35,7 +41,8 @@ agentd 不常驻：一轮运行比起它的那次 tick 活得久，所以执行
 ## Transport 接口（`agentd/transports/`）
 `os`、`join`、`quote`、`default_run_root`、`mkdir(path, clean)`、`write_text`、`read_text`（不存在返回 None）、`grep_first(path, needle)`、`tail(path, n)`、`runner(run_dir, cwd, command, stdout_name)`、`launch(task, script, run_dir)`、`kill(task, run_dir)`、`forget(task)`、`process_count(name)`（None = 不可达）。
 - `local`：Linux 本机文件 + `setsid -f`；kill = 对 `pid.txt` 的进程组发 SIGTERM。
-- `warpgate-ssh`：Windows，经 `win10-ps.sh`（PowerShell `-EncodedCommand`）和 `win10-put.sh`（分块上传 + SHA-256 校验）；文件读取用 base64 标记回传；kill = `taskkill /T /F /PID <pid.txt>` + `schtasks /End /Delete`。脚本目录由 `agentd.helpers_dir`（或终端 `helpers_dir`）配置；脚本目前写死 `--target win10`。
+- `warpgate-ssh`：Windows，经 `win10-ps.sh`（PowerShell `-EncodedCommand`）和 `win10-put.sh`（分块上传 + SHA-256 校验）；文件读取用 base64 标记回传；kill = `taskkill /T /F /PID <pid.txt>` + `schtasks /End /Delete`。脚本目录由 `agentd.helpers_dir`（或终端 `helpers_dir`）配置；脚本目前写死 `--target win10`。路径都放进 PowerShell 单引号字面量（`'` 双写）；`schtasks /TR` 里脚本路径用 `\"…\"` 包裹，依赖 Windows PowerShell 5.1 的旧式原生参数传递（PowerShell 7.3+ 的 Standard 模式下需改写）。runner 进不了 repo 时写 `exit=97` 结束。
+- Codex 续线程：`codex exec resume <thread>` 不接受 `-C`/`-s`，`resume` 模板里不要写；工作目录由 runner 先进入 repo 保证，沙箱沿用 Codex 对该会话/全局配置的默认值（若需强制，用 `-c 'sandbox_mode="workspace-write"'`，上线前在 win10 上验证）。
 
 ## 新增一个执行器
 1. `agentd/executors/<name>.py`：继承 `RunnerExecutor`，设 `stdout_name`，实现 `collect`（必要时覆盖 `resume`/`command`）。完全不同的形态（如 HTTP API）可直接继承 `Executor`，只要 handle 可序列化。