PAD-12: per-terminal transport (direct Tailscale SSH or Warpgate, pre-session fallback, pinned host keys, agent key from Vault), one-call win10 launch and one-call collect, remote call timings, agentd ping

docs/design.md

@@ -3,7 +3,7 @@
 Plane 看板驱动的通用 agent 调度服务：任何人/agent 在 Plane 建工作项并指派给一个"终端"，agentd 在该终端起对应的 CLI agent（Codex、Claude Code、脚本…）执行，把结果贴回工作项并流转状态。调度是确定性代码，模型只出现在执行器和总指挥里。
 
 ## 1. 目标与非目标
-- 目标：多项目隔离（一份配置一段）、多终端（本机/经 Warpgate 的远程机）、多 CLI（执行器适配器）、多轮（线程持久、进程不常驻）、失败可解释可重试、凭据只经 Vault 注入内存、任何会话可接手。
+- 目标：多项目隔离（一份配置一段）、多终端（本机/经 Warpgate 或 Tailscale 直连的远程机）、多 CLI（执行器适配器）、多轮（线程持久、进程不常驻）、失败可解释可重试、凭据只经 Vault 注入内存、任何会话可接手。
 - 非目标：不是工作流引擎（无 DAG/分支，顺序交给 Plane "blocked by"——**TODO：阶段 1 尚未实现**，调度不读 blocked-by 关系，被阻塞的 Todo 项照样会被拾起）；不替代 Plane/Temporal 的界面；不做账号系统；不存密钥。
 
 ## 2. 架构
@@ -18,7 +18,7 @@ Plane ──webhook（HMAC）即时触发 / cron 轮询兜底──► agentd（
 阶段 3 之后调度核心搬到 Temporal（workflow = 一个工作项的生命周期，activity = 起执行器/等结果/回帖），用 Temporal UI 看运行与重试。
 
 ## 3. 概念与契约
-- **终端（terminal）**：怎么到达一台机器 — `transport`（local | warpgate-ssh）、`os`、`launch`（subprocess | schtasks | nohup）、`repo`、`plane_user`（回帖身份，对应 Vault 键）、`concurrency`、`capabilities`、可用 `executors`。
+- **终端（terminal）**：怎么到达一台机器 — `transport`（local | warpgate-ssh | direct-ssh，§9）、`os`、`launch`（subprocess | schtasks | nohup）、`repo`、`plane_user`（回帖身份，对应 Vault 键）、`concurrency`、`capabilities`、可用 `executors`。
 - **执行器（executor）**：某个 CLI 的适配器 — 起一轮的命令模板、续线程命令模板、`resume: true|false`、可用模型、默认推理强度、沙箱参数、最后消息取法、线程 ID 取法。
 - **路由（routing）**：`by_assignee`（Plane 用户 → 终端）、`by_label`（`exec:*`、`model:*`、`effort:*`、`needs-*` 串行组、`cap:*` 能力、`budget:*` 时限）、每终端默认执行器。
 - **工作项契约**：正文 = 任务书；评论 = 消息；执行器最后消息首行 ∈ `[review] | [question] | [blocked] | [progress]`；agentd 回帖格式固定（轮次、run id、退出码、日志路径）。
@@ -76,7 +76,7 @@ notify: {kind: none}     # 钩子：核心每次改状态调用 Agentd.notify()
 ```
 agentd/            调度核心、plane 客户端、vault 注入、状态存储（json/sqlite）、心跳
 agentd/executors/  codex.py claude_code.py shell.py（适配器契约见 docs/executor-contract.md）
-agentd/transports/ local.py warpgate_ssh.py（远程 Linux/macOS：bash -c 经中继；Windows：helper 脚本 + schtasks）
+agentd/transports/ local.py warpgate_ssh.py（远程 Linux/macOS：bash -c；Windows：PowerShell + schtasks；Warpgate 通道）direct_ssh.py（Tailscale 直连通道，PAD-12）
 agentd/web/        配置页面（阶段 2）：读写 YAML + schema 校验 + 连通/冒烟测试 + 最近运行
 cli/               agentd tick|new|show|comment|state|assign|smoke|webhook-serve|check-config
 systemd/           plane-agentd-webhook.service（LXC 上的 webhook 接收端）
@@ -98,10 +98,16 @@ docs/              design.md executor-contract.md runbook.md
 - 网络（2026-10-21）：LXC 到 NAS 的 tailnet 路径依赖 OPNsense 的静态端口出站 NAT 规则 + LXC tailscaled 固定 UDP 41642，已直连（详见 docs/deploy-lxc.md §2.1）；曾因 DERP 导致调度器暂回 oregon，已于同日切回 LXC。
 - Plane VM（Plane 3.3.3，PVE VM 506 plane-02）只跑 Plane：它是设备化节点（固定版本、每日备份停写路径），不放 agentd。
 - 阶段 1–2：agentd 跑在 oregon（已有 Vault 客户端、Warpgate 中继脚本、Claude Code、现有 worker 状态），cron 拉起；配置页面同进程，只监听 tailnet 地址。
-- 阶段 3 起（**2026-10-21 PAD-11 已切换**）：迁到 PVE 上的精简 LXC `agentd-01`（CT 600，root，仓库 `/opt/plane-agentd`，状态 `/var/lib/plane-agentd`，日志 `/var/log/plane-agentd`；1 vCPU / 1–2 GB，tailnet + 内网 10.77.10.0/24，与 Plane/Temporal 同网段，webhook 走内网）。**LXC 上不装任何 agent CLI**，只有 Python 3.10+、PyYAML、Agent Vault 客户端、ssh 客户端；所有终端（win10、oregon、mac…）一律远程启动（`transport: warpgate-ssh`），LXC 只负责调度、回帖、通知。对外访问经 Warpgate HTTP target，复用既有登录。
+- 阶段 3 起（**2026-10-21 PAD-11 已切换**）：迁到 PVE 上的精简 LXC `agentd-01`（CT 600，root，仓库 `/opt/plane-agentd`，状态 `/var/lib/plane-agentd`，日志 `/var/log/plane-agentd`；1 vCPU / 1–2 GB，tailnet + 内网 10.77.10.0/24，与 Plane/Temporal 同网段，webhook 走内网）。**LXC 上不装任何 agent CLI**，只有 Python 3.10+、PyYAML、Agent Vault 客户端、ssh 客户端；所有终端（win10、oregon、mac…）一律远程启动（`transport: warpgate-ssh` 或 `direct-ssh`，见下文"终端通道"），LXC 只负责调度、回帖、通知。对外访问经 Warpgate HTTP target，复用既有登录。
 - 远程启动的通用实现（P1-6，已实现）：Linux/macOS 经 Warpgate SSH（`agent-access.py run --target <终端 target> -- bash -c …`）上传 `prompt.md`/`run.sh` 并一次调用内启动，`setsid nohup` 脱离会话（macOS 用 perl `POSIX::setsid`），轮询 `exit.txt`，从终端上的输出文件取回最后消息/线程 ID，kill 按进程组 + 会话；中继目标名由终端配置给出。oregon 已切到这条路径（调度器暂仍在 oregon，启动经 Warpgate 回到本机）。部署步骤：`docs/deploy-lxc.md`。
 - 防重复启动（PAD-11）：启动调用之前先把计划中的运行（run id、终端、handle、记账字段）作为 `launching` 标记落盘；启动调用失败/超时或 agentd 中途退出时，下一 tick 探测运行目录（`exit.txt`/`launch.pid`/`pid.txt`）：有 → 接管；无 → 同一 run id 换新目录 `<run_id>-r2` 重启（不清空旧目录）；探测不通 → 保留标记并占住终端槽位。transport 拒绝清空含 pid 文件的运行目录。某终端中继失败时本 tick 余下操作跳过该终端，其他终端照常。
-- Windows 仍用 helper 脚本 `win10-ps.sh` / `win10-put.sh`（仓库 `tools/win10/`，写死 `--target win10`）+ 计划任务。**TODO（统一）**：Windows 也改走 `relay()`（argv = `powershell.exe -EncodedCommand …`，文件同样 base64 分块），删掉对 helper 脚本与 `helpers_dir` 的依赖，LXC 上就不必再复制这两个脚本。
+- Windows 走 Warpgate 时仍用 helper 脚本 `win10-ps.sh` / `win10-put.sh`（仓库 `tools/win10/`，写死 `--target win10`）+ 计划任务：`agent-access.py run` 把 ssh 的 stdin 接到 /dev/null（`run_remote` 里 `stdin=subprocess.DEVNULL`），cmd.exe 命令行又限 8191 字符，文件只能按 2400 字符分块上传。走 `direct-ssh` 时不用 helper 脚本。收尾读取在 Warpgate 上也已合成一次调用（脚本足够短，放得进 `-EncodedCommand`）。
+- **终端通道（PAD-12，2026-10-22）**：LXC 到每个远程终端走哪条路，按终端配置 `transport`：
+  - `warpgate-ssh`（原有，缺省）：`agent-access.py run` 经 Warpgate SSH 网关（`115.28.210.101:2222`）。每次调用都要取 Vault 凭据、与网关握手、密码认证、网关再连终端，LXC 上实测中位数约 9 s（客户端 + vault 0.8 s、网关 banner/kex 1.8 s、密码认证 2.2 s、二跳 + 命令 2–5 s）。客户端写死 `ControlMaster=no`，连接不能复用，数据只能放 argv。一次 win10 启动约 10 次串行调用（busy 检查、mkdir/清空、prompt.md 分块上传 + 重置 + 解码、run.ps1、schtasks）：GW-26-1 用了 91 s；收尾约 7 次，约 60 s。
+  - `direct-ssh`（新）：LXC 经 Tailscale 直连终端的 sshd（`ssh: {host, user, port, host_key}`）。认证用一把专用 ed25519 密钥：Vault 键 `AGENTD_SSH_KEY` 经 `--secret-env` 进 tick 进程，载入本进程私有的 ssh-agent（0700 临时目录里的套接字，`ssh-add -` 从 stdin 读）后立即从环境变量删掉，子进程拿不到；不落盘，不进 argv、日志、Plane 评论或异常信息。主机公钥钉死在配置里，`StrictHostKeyChecking=yes`，known_hosts 由钉住的公钥生成，只含这一把。`ControlMaster=auto`，`ControlPersist=60`，套接字放在只有 root 可进的 `agentd.ssh_dir`（`/run/plane-agentd/ssh`），名字是 `<host_key 指纹 8 位>-%C`：pin 改了就换新连接，不会沿用按旧 pin 校验过的主连接。密钥在 CLI 启动时就从环境变量里拿走（第一次直连之前起的子进程也继承不到）。脚本走 stdin：Windows 是一段固定的 PowerShell 引导（`-EncodedCommand`），从 stdin 读真正脚本的 base64；Linux 是固定的 bash 加载器。所以每个操作恰好一次调用，不受 argv 长度限制。win10 启动（建目录、清空并遵守 HASPID 拒绝、写 UTF-8 无 BOM 的 prompt.md/run.ps1、注册并启动计划任务）一次；收尾一次（exit、最后消息、线程 ID、stderr 尾、事件尾）加删计划任务一次。oregon 启动一次，收尾一次。busy 检查和 poll 仍各一次。实测直连路径：win10 RTT 27 ms（握手到认证 0.24 s），oregon RTT 233 ms（握手 2.2 s）。目标：派单延迟 ≤ 15 s。
+  - `fallback: warpgate-ssh`（可选，需要 `target`）：直连**在远程命令运行之前**失败时（ssh 退出 255、没有任何 stdout，且 stderr 里有 ssh 自己在行首打印的连接超时/拒绝/无路由/解析失败/认证失败/agent 错误，或者本进程没拿到密钥。远程加载器把脚本自己的 255 改报 254，所以 255 只可能来自 ssh；有 stdout 就说明命令已经跑过），这个操作改走 Warpgate 重做，本 tick 里该终端余下的操作也都走 Warpgate，`agentd.log` 记一行。**主机公钥不符（包括终端不提供 ssh-ed25519 主机密钥）绝不回退**：按安全事件处理，`agentd.log` 记 `SECURITY …` 行，该终端本 tick 标为 down。命令可能已经运行过的失败（超时、会话中途断开、认不出的 255）不会换路径重试。启动这种非幂等操作仍靠 `launching` 标记加下一 tick 的探测/接管（`resolve_launch`），不存在双启动的路径。直连的每个操作都只有一次远程调用，所以"整个操作换路径重做"不会重复任何副作用。
+  - **取舍**：直连绕过了 Warpgate 的会话录像和集中授权。访问控制改由终端自己负责：authorized_keys 只认这把专用密钥，并限定来源 `from="100.69.78.124"`（LXC 的 tailnet 地址）。用户已逐终端批准（win10、oregon，2026-10-22）。回滚：把该终端的 `transport` 改回 `warpgate-ssh`（`ssh`/`fallback` 可以留着，此时被忽略）。
+  - 观测：每次远程调用在 `<log_dir>/remote.log` 记一行（`term= via=direct|warpgate|fallback op= ms= rc=`）。部署后用 `agentd ping <终端> [--transport direct-ssh|warpgate-ssh]` 验证。步骤见 `docs/deploy-lxc.md` §9。
 
 ## 10. Webhook 触发（PAD-7）
 - **形态**：`agentd webhook-serve`（`agentd/webhook.py`，只用标准库）常驻在 LXC 上（systemd `plane-agentd-webhook`），Plane 工作区级 webhook（事件 `issue` + `issue_comment`）投到 `http://10.77.10.249:8790/plane`。它不自己调度，只是**提前跑一次 cron 的 tick 脚本**：调度仍然只有一份代码、一把锁、一个状态文件；cron 每 2 分钟照跑，webhook 丢了/接收端挂了只是退回到轮询延迟。
@@ -109,6 +115,6 @@ docs/              design.md executor-contract.md runbook.md
 - **路由**：`data.project` ∈ 配置的项目 → 200 并触发；否则（别的项目、删除事件没有项目）→ 202 忽略。不按事件类型或操作者过滤：agentd 自己回帖/改状态也会产生投递，结果是每次有动作的 tick 之后多一次 tick（空闲 tick 不写 Plane，不会循环）。
 - **合并与补跑**：第一条投递后等 3 s，期间的投递合并成一次 tick；tick 运行中又来的投递 → 结束后再跑一次（运行中的 tick 可能在变化之前读过 Plane）。锁被占（cron/手工 tick；脚本 `flock -n -E 75`，`cli tick` 撞上 agentd 状态锁也退出 75）→ 每 15 s 重试，最长 2 min，之后交给 cron。
 - **进程隔离**：tick 用 `systemd-run --scope` 跑在独立 cgroup 里，重启/停止接收端不会杀掉正在跑的 tick（tick 可能正在启动远程运行）。
-- **延迟构成**：投递 → tick 开始 ≈ 3 s 合并窗口；tick 本身 = vault 取 token（1–2 s）+ 读 Plane + 先 poll 每个在途运行（每个中继调用约 10 s）+ 启动（中继约 12 s；win10 上传更久）。`[worker] 第 k 轮开始` 评论在启动调用返回之后才发，所以"建项 → 开始评论"受中继成本限制，而不是触发方式。
+- **延迟构成**：投递 → tick 开始 ≈ 3 s 合并窗口；tick 本身 = vault 取 token（1–2 s）+ 读 Plane + 先 poll 每个在途运行（每个中继调用约 10 s）+ 启动（中继约 12 s；win10 上传更久）。`[worker] 第 k 轮开始` 评论在启动调用返回之后才发，所以"建项 → 开始评论"受中继成本限制，而不是触发方式。PAD-12 之后，直连终端每次调用不再是约 10 s，而是亚秒到约 2 s（§9 终端通道）。
 - **Plane 的 SSRF 防护**：Plane（≥1.4 / 商业版 3.x）拒绝解析到私有/CGNAT 地址的 webhook URL（创建时和每次投递时都查），除非 Plane 的环境里有 `WEBHOOK_ALLOWED_IPS`（CIDR 列表）或 `WEBHOOK_ALLOWED_HOSTS`。内网接收端需要在 Plane 的 api 与 worker 容器环境里设 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`（改 `/opt/plane/plane.env` 与渲染的 `/var/plane/docker-compose.yml`，重建 api/worker，见 deploy-lxc §8）。2026-10-22 已应用（同时重建了 webhook-consumer、outbox-poller、automation-consumer、beat-worker，见 deploy-lxc §8），webhook 已启用，cron 保留为兜底。Plane 建出的是 v2 webhook（`plane/webhook/bgtasks/webhook_task.py` 的 `send_webhook`，负载 `{version: v2, event, entity_type, data, …}`），签名同为 HMAC-SHA256(secret, json.dumps(payload))，`data.project` 路由照常，接收端无需改动。
 - **心跳里的跳过原因**：每个 tick 把没派出去的 Todo 项和原因写进 `heartbeat.json` 的 `skipped`（`concurrency 1/1 (GW-15)`、`serialize_group game held by GW-4`、`busy_process codex (1 running, not started by agentd)`、`relay down`、`no route for assignee kappiee`、`start failed: …`），同一项的原因变化时才写一行日志。