plane-agentd/docs/executor-contract.md

执行器契约

agentd 不常驻：一轮运行比起它的那次 tick 活得久，所以执行器的一切都必须能从可 JSON 序列化的 handle 恢复（handle 存在 state/agentd-state.json 的 inflight.handle 里）。

接口（agentd/executors/base.py）

成员	说明
resume: bool	能否续线程。False 时每轮都是新线程（有前序轮次时附交接摘要）。
handle(run) -> handle	不接触终端，算出 start(run) 将返回的 handle（core 在启动前把它写进 launching 标记）。
start(run: Run) -> handle	起一轮，立即返回；不得阻塞到运行结束。抛异常不代表一定没启动：core 下一 tick 用 probe 判断。
probe(handle) -> [names]	运行目录里的启动证据（exit.txt/launch.pid/pid.txt 中存在的）；空 = 没启动；终端不可达抛 TransportError。
poll(handle) -> "running" | "finished"	便宜的完成检测。
collect(handle) -> ExecResult	只在 finished 后调用，可重复调用（幂等）：Plane 回帖失败时下一 tick 会再 collect。
kill(handle)	超时时结束整个进程树。
forget(handle)（可选）	collect 之后清理（如删除计划任务）。

Run(run_id, repo, prompt, model, effort, tier, thread_id, script, dir_name)：thread_id 非空即续该线程；dir_name 是运行目录名/计划任务名（缺省 = run_id，重新启动时为 <run_id>-r2 等）。 ExecResult(last_message, exit_code, thread_id, log_paths, tail)：last_message 原样回帖，首行应为 [review]/[question]/[blocked]/[progress]；thread_id 供下一轮续接；tail 是失败说明里的"最后一帧"（stderr 尾部/最后事件）。

执行器不接触 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>/<dir_name>（清空旧文件；目录里已有 pid.txt/launch.pid 时拒绝并报 HASPID），写 prompt.md。transport 有 start_run 时（远程终端），建目录、写 prompt.md 与 runner、启动由 transport 一起做：直连（direct-ssh）和远程 POSIX 是一次调用，Windows 经 Warpgate 时仍逐步上传。
2. 用配置里的命令模板生成命令：run（新线程）或 resume（续线程）。占位符：{repo} {model} {effort} {tier} {out} {thread} {perm} {script} {run_dir}；未知占位符原样保留。{tier} 展开为 tier_arg（如 -c 'service_tier="fast"'），无 tier 时为空。tier 来源：tier:<x> 标签或 routing.by_label 的 tier，否则执行器的 tier_defaults[<model>]；tier:none 表示不加档位参数。模板首词若在终端 bins 里，替换为绝对路径（Windows 前加 &）。参数请用单引号，bash 和 PowerShell 都认。
3. transport 生成 runner 脚本（Linux run.sh，Windows run.ps1）：进入 repo，写 pid.txt/started.txt，把 prompt.md 从 stdin 喂给命令，stdout → stdout_name，stderr → stderr.txt，结束写 exit.txt（exit=N at …）。
4. transport 分离启动（本机 setsid -f bash run.sh；远程 Linux setsid nohup bash run.sh &，macOS 用 perl POSIX::setsid，$! 记入 launch.pid；Windows 一次性计划任务 agentd-<run_id>）。
5. poll = exit.txt 是否存在；collect 由各适配器从终端上保存的文件解析（远程时读回，不依赖调度器本机有任何 CLI）。适配器把要读的东西列成 COLLECT（("read", 文件)、("grep", 文件, 子串)、("tail", 文件, n)），经 transport.fetch 一次调用取回；transport 没有 fetch 时逐个读：

适配器	stdout	最后消息	线程 ID
codex	events.jsonl	last.md（-o {out}）	thread.started 事件的 thread_id
claude-code	out.json	JSON 的 result（is_error 时为空，进失败流程）	JSON 的 session_id
shell	stdout.txt	last.md（脚本可写 {out}），否则 stdout 尾部 6000 字	无（resume 恒 false）

配置里的 thread_from / last_message 目前只是说明性字段，解析逻辑在适配器里。

Transport 接口（agentd/transports/）

os、join、quote、default_run_root、mkdir(path, clean)（clean 遇到 pid 文件必须拒绝）、probe(run_dir, names)（存在的文件名列表，一次调用）、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 = 不可达）；可选 start_run(task, run_dir, files, script_name)（建目录 + 写文件 + 启动）和 fetch(run_dir, ops)（一次读回多个结果，collect 用）。远程 transport 的脚本由一个"通道"送达：warpgate-ssh（agent-access.py run，只能走 argv）或 direct-ssh（Tailscale 直连 OpenSSH，脚本走 stdin，每个操作一次调用；可配 fallback: warpgate-ssh，见 design §9）。直连在命令运行前失败时抛 Unreached（RoutedTransport 据此换到兜底通道），主机公钥不符时抛 HostKeyError（不回退）；process_count 不能吞掉 Unreached。

• local：Linux 本机文件 + setsid -f；kill = 对 pid.txt 的进程组发 SIGTERM。用于调度器与执行器同机的部署和测试。
• warpgate-ssh + os: linux|darwin（PosixWarpgateTransport）：每个操作是一次 agent-access.py --config <vault.config> run --target <target> -- bash -c '<script>'（relay()，目标名取终端 target，缺省为终端名；客户端把 argv shlex.join 后交给目标账户的登录 shell，stdin 为 /dev/null）。文件：base64 放进 printf %s '<b64>' | base64 -d，超过 60000 字符分块追加再解码，回显字节数校验；读文件/grep_first/tail 的结果以 B64= 标记回传。runner 与本机相同（run.sh），setsid nohup 脱离 SSH 会话（pid = pgid = sid）；kill = 对该进程组 kill -TERM -- -<pid> + pkill -TERM -s <pid>，最多等 5 s 后 KILL，exit.txt 已存在时不发信号（防 pid 复用）；process_count = pgrep -x。repo/run_root 必须是远程绝对路径。每次调用约 10–14 s，所以启动只用一次调用。
• warpgate-ssh + os: windows（WindowsWarpgateTransport）：经 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（TODO：改走同一个 relay()，argv 为 powershell.exe -NoProfile -NonInteractive -EncodedCommand <b64>，去掉 helper 脚本）。路径都放进 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 可序列化。
2. 在 agentd/executors/__init__.py:make_executor 里登记 adapter 名；config/schema.json 的 executor.adapter enum 和 config.semantic_errors 的白名单同步加上。
3. 配置 executors.<name>：adapter、run、resume、models、default_effort 等；把它加进相应终端的 executors，需要时在 routing.by_label 加 exec:<name>。
4. 在 tests/ 加一个用假二进制（bins 指向临时脚本）的本机测试，参照 tests/test_local_runner.py。

新增一个终端

1. terminals.<name>：transport、os、launch、repo、plane_user（该终端回帖身份的 Plane 显示名）、token_key（Vault 键名，同名环境变量）、concurrency、capabilities、executors，可选 bins、run_root、busy_processes（这些进程在跑而 agentd 没有在途运行时不派单）。
2. 项目 routing.by_assignee 加 <plane_user>: <name>，default_executor 加默认执行器。
3. cron 的 agent-access.py exec 加 --secret-env <token_key>=<token_key>（agentd check-config 会打印完整参数）。
4. agentd smoke <PROJECT> <name> 验证一轮往返。 远程 Linux/macOS 机器不需要新代码：transport: warpgate-ssh, target: <Warpgate target>, os: linux|darwin, launch: nohup，repo/run_root/bins 写远程绝对路径（步骤见 docs/deploy-lxc.md §7）。全新的 transport 类型需在 agentd/transports/ 实现上面的接口并在 make_transport 登记。