From 4ba6d0ca5f3f74091d3af1eeb232abdcd21220c0 Mon Sep 17 00:00:00 2001
From: "jj.wang" <jj.wang@alphabets.cn>
Date: Wed, 21 Oct 2026 13:52:19 +0000
Subject: [PATCH] =?UTF-8?q?Docs:=20webhook=20receiver=20(runbook,=20design?=
 =?UTF-8?q?=20=C2=A710,=20deploy-lxc=20=C2=A78),=20PAD-7=20rollout=20recor?=
 =?UTF-8?q?d?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Runbook: service, endpoint, signature, logs, secret rotation, disabling,
heartbeat skipped reasons, new failure rows. Design: webhook trigger design,
notify hook, Plane SSRF guard (WEBHOOK_ALLOWED_IPS). Deploy: install steps.
Record: synthetic-delivery acceptance and measured latencies.
---
 docs/deploy-lxc.md | 15 +++++++++++++++
 docs/design.md     | 29 +++++++++++++++++++++--------
 docs/runbook.md    | 34 ++++++++++++++++++++++++++++++++--
 3 files changed, 68 insertions(+), 10 deletions(-)

diff --git a/docs/deploy-lxc.md b/docs/deploy-lxc.md
index 23f5f73..b89f01d 100644
--- a/docs/deploy-lxc.md
+++ b/docs/deploy-lxc.md
@@ -100,3 +100,18 @@ python3 -m unittest && python3 cli/agentd check-config
    远程 shell 是目标账户的登录 shell（bash/zsh 均可，agentd 发的是 `bash -c '<script>'`）；终端需有 `bash base64 nohup pgrep pkill`（Linux 另需 `setsid`，macOS 需 `perl`）。
 4. Plane：建用户 `mac`，token 存 Vault 键 `PLANE_MAC_API_TOKEN`；项目 `routing.by_assignee` 加 `mac: mac`，`default_executor` 加 `mac: claude-code`；`cron/agentd-tick-lxc.sh` 加 `--secret-env PLANE_MAC_API_TOKEN=PLANE_MAC_API_TOKEN`。
 5. 提交、推送、LXC `git pull`；`cli/agentd check-config`，然后 `cli/agentd smoke GWENT mac --watch`。
+
+## 8. Webhook 接收端（PAD-7）
+1. 网络：Plane VM 10.77.10.68 与 LXC 10.77.10.249 同在 10.77.10.0/24，接收端只听 `10.77.10.249:8790`（LXC 内无防火墙）。**Plane 侧前提**：Plane 默认拒绝内网 webhook 地址（"The webhook URL is not allowed. Provide a publicly reachable HTTP or HTTPS URL."），要在 Plane 的 api 与 worker 容器环境里加 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32` 并重建这两个容器（design §10）。纯 http 本身是允许的（http/https 都行）。
+2. 密钥：Plane 建 webhook 时生成、只显示一次 → `tools/plane-webhook.py create http://10.77.10.249:8790/plane` 直接写进 Vault `PLANE_WEBHOOK_SECRET`（建出来是停用状态；在 oregon 上以 kappiee 管理员会话运行，见 runbook "Webhook"）。核对长度：`agent-access.py … exec --secret-env S=PLANE_WEBHOOK_SECRET -- python3 -c 'import os;print(len(os.environ["S"]))'`。
+3. 代码与服务（LXC）：
+   ```bash
+   cd /opt/plane-agentd && flock /var/lib/plane-agentd/cron.lock git pull
+   cp systemd/plane-agentd-webhook.service /etc/systemd/system/ && systemctl daemon-reload
+   systemctl enable --now plane-agentd-webhook
+   curl -s http://10.77.10.249:8790/healthz       # {"ok": true, ...}
+   tail /var/log/plane-agentd/webhook.log           # listening on http://10.77.10.249:8790/plane (tenants: GWENT)
+   ```
+   单元文件复用 cron 脚本的 vault 客户端调用方式：`python3 -I /root/.local/share/server-access-client/agent-access.py --config <identity> exec --secret-env PLANE_WEBHOOK_SECRET=PLANE_WEBHOOK_SECRET --timeout 315360000 -- python3 /opt/plane-agentd/cli/agentd … webhook-serve --bind 10.77.10.249 --port 8790`，`Restart=always`。tick 由接收端经 `systemd-run --scope … cron/agentd-tick-lxc.sh` 拉起（同一把 `cron.lock`，`flock -n -E 75`）。
+4. 启用 Plane 侧：`tools/plane-webhook.py patch <id> is_active=true`，然后 `systemctl restart plane-agentd-webhook`（若第 2 步之后密钥变过）。
+5. 验证：随便改一个 GWENT 工作项 → `webhook.log` 出现 `decision=tick` 和 `tick start`/`tick done`；错签名请求得 401 且没有 tick；`journalctl -u cron` 里 cron 仍每 2 分钟一次；`systemctl restart plane-agentd-webhook` 后 `/healthz` 恢复。
diff --git a/docs/design.md b/docs/design.md
index 688c246..4b1b68b 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -8,12 +8,12 @@ Plane 看板驱动的通用 agent 调度服务：任何人/agent 在 Plane 建
 
 ## 2. 架构
 ```
-Plane ──webhook v2（HMAC）/ 轮询兜底──► agentd（接收端 + 调度核心 + 执行器适配器）
+Plane ──webhook（HMAC）即时触发 / cron 轮询兜底──► agentd（接收端 + 调度核心 + 执行器适配器）
                                         │ 按 assignee→终端、label→执行器/模型，串行组，重试，超时，心跳
                         ┌───────────────┼───────────────┐
                   codex（远程/本机）  claude-code（本机/远程）   shell
                         └───────────────┴───────────────┘
-                 执行器只产出"最后消息 + 产物路径"；agentd 统一回帖、改状态、通知（ntfy）
+                 执行器只产出"最后消息 + 产物路径"；agentd 统一回帖、改状态、通知（notify 钩子，暂为空操作）
 ```
 阶段 3 之后调度核心搬到 Temporal（workflow = 一个工作项的生命周期，activity = 起执行器/等结果/回帖），用 Temporal UI 看运行与重试。
 
@@ -34,7 +34,7 @@ Plane ──webhook v2（HMAC）/ 轮询兜底──► agentd（接收端 + 调
 | 环境类（焦点丢失/弹窗/断网） | 当 blocked 处理，暂停同串行组的派发 | Waiting |
 | 运行中工作项被移出 In Progress | 结束任务进程，回帖"运行已取消：工作项状态被改为 X"，释放终端槽位/串行组，保留线程 | 不改 |
 | 连续 `max_progress_rounds`（默认 12）轮 `[progress]` | 回帖说明，不再续跑 | Waiting → 应答者 |
-| agentd 自身 | cron 拉起；心跳 10 min 无更新 → ntfy 报警 | — |
+| agentd 自身 | cron 拉起（webhook 只是提前触发）；心跳 10 min 无更新 → 报警（notify 钩子，未实现） | — |
 回到 Todo 的工作项无条件重新拾起；逻辑性失败永不自动重试。
 
 阶段 1 的具体取舍（均有单测）：
@@ -58,7 +58,6 @@ executors:
 projects:
   GWENT:
     id: 79cb5a60-aa4f-4138-9864-1dd70426e665
-    webhook_secret_key: PLANE_WEBHOOK_GWENT
     states: {todo: Todo, running: In Progress, waiting: Waiting, review: Review, done: Done}
     reviewer: oregon
     routing:
@@ -67,7 +66,10 @@ projects:
       default_executor: {win10: codex, oregon: claude-code}
     retry: {transient_max: 3, backoff_minutes: [2, 5, 10]}
     timeout_hours: 4
-    notify: {ntfy_topic: gwent, on: [waiting, review, failed]}
+webhook: {bind: 10.77.10.249, port: 8790, path: /plane, secret_key: PLANE_WEBHOOK_SECRET,
+          tick_command: [systemd-run, --scope, --quiet, --collect, /opt/plane-agentd/cron/agentd-tick-lxc.sh],
+          debounce_seconds: 3, retry_seconds: 15, retry_window_seconds: 120}
+notify: {kind: none}     # 钩子：核心每次改状态调用 Agentd.notify()，none = 空操作
 ```
 
 ## 6. 仓库布局
@@ -76,7 +78,8 @@ agentd/            调度核心、plane 客户端、vault 注入、状态存储
 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/web/        配置页面（阶段 2）：读写 YAML + schema 校验 + 连通/冒烟测试 + 最近运行
-cli/               agentd new|show|comment|state|assign|smoke
+cli/               agentd tick|new|show|comment|state|assign|smoke|webhook-serve|check-config
+systemd/           plane-agentd-webhook.service（LXC 上的 webhook 接收端）
 config/            agentd.yaml（示例 + 实际）、schema.json
 docs/              design.md executor-contract.md runbook.md
 ```
@@ -84,12 +87,12 @@ docs/              design.md executor-contract.md runbook.md
 ## 7. 阶段
 1. **核心**：配置驱动调度（轮询）、codex-remote(win10) + claude-local(oregon) 两个执行器、线程续接与重建、失败说明与重试、心跳、CLI；gwent 项目作为首个租户切换过来（替换现有 board-worker-plane）。
 2. **配置页面**：单页，三个标签（终端/执行器/路由）+ 状态条；保存即校验、提交 Git、热加载；不显示密钥。
-3. **Webhook + ntfy**：Plane webhook v2 签名校验、即时触发；ntfy 通知 Waiting/Review/失败；轮询保留兜底。前提：Plane VM 进 tailnet 或接收端放在可达位置。
+3. **Webhook + 通知**：Plane webhook 签名校验、即时触发，轮询保留兜底——**PAD-7 已实现**（§10）。通知 Waiting/Review/失败：只留了空操作钩子 `notify: {kind: none}`（没有 ntfy 服务）。
 4. **Temporal**：调度核心迁为 workflow/activity，获得重试/超时/历史/UI；agentd 变为 worker + webhook 入口。
 5. **Gitea 联动**：执行器产物以分支/PR 提交并回帖链接；可选 Gitea webhook 回写 Plane。
 
 ## 8. 安全
-配置里只有 Vault 键名；token 由 `agent-access.py exec --secret-env` 注入 agentd 进程；执行器不持有 Plane 凭据、不能直接改工作项；webhook 按项目签名校验；页面仅 tailnet 可达，登录走既有网关。
+配置里只有 Vault 键名；token 由 `agent-access.py exec --secret-env` 注入 agentd 进程；执行器不持有 Plane 凭据、不能直接改工作项；webhook 是工作区级的一个密钥（Vault 键 `PLANE_WEBHOOK_SECRET`，只经 `--secret-env` 进接收端进程，不传给子进程），HMAC 校验失败 401，只认配置里的项目；接收端只听内网地址；页面仅 tailnet 可达，登录走既有网关。
 
 ## 9. 部署位置
 - Plane VM（plane-01）只跑 Plane：它是设备化节点（固定版本、每日备份停写路径），不放 agentd。
@@ -98,3 +101,13 @@ docs/              design.md executor-contract.md runbook.md
 - 远程启动的通用实现（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 上就不必再复制这两个脚本。
+
+## 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 丢了/接收端挂了只是退回到轮询延迟。
+- **校验**：`X-Plane-Signature` = HMAC-SHA256(密钥, 请求体) 的十六进制（Plane 签 `json.dumps(payload)` 并原样发送）；常量时间比较，先比原始字节、再比重新序列化的结果。缺失/不符 → 401，不触发。
+- **路由**：`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 轮开始` 评论在启动调用返回之后才发，所以"建项 → 开始评论"受中继成本限制，而不是触发方式。
+- **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`。
+- **心跳里的跳过原因**：每个 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: …`），同一项的原因变化时才写一行日志。
diff --git a/docs/runbook.md b/docs/runbook.md
index 023d505..03bb8c2 100644
--- a/docs/runbook.md
+++ b/docs/runbook.md
@@ -52,12 +52,32 @@ cli/agentd smoke GWENT win10 --labels model:sol --watch   # --labels 给冒烟
 ```
 CLI 以 `--as <terminal>` / `agentd.cli_terminal` / 第一个有 token 的终端的身份操作。
 
+## Webhook（PAD-7：Plane 事件即时触发 tick）
+cron 每 2 分钟一次的 tick 保留作兜底；另有常驻接收端，Plane 一有工作项/评论变化就立刻触发一次 tick。
+- **服务**：LXC `plane-agentd-webhook.service`（单元文件在仓库 `systemd/`，`Restart=always`）= `agent-access.py … exec --secret-env PLANE_WEBHOOK_SECRET=PLANE_WEBHOOK_SECRET --timeout 315360000 -- python3 /opt/plane-agentd/cli/agentd webhook-serve --bind 10.77.10.249 --port 8790`。只听内网地址；密钥只在进程环境里，agentd 起的子进程（tick 脚本）环境里去掉了它。
+- **端点**：`POST http://10.77.10.249:8790/plane`；`GET /healthz` → `{"ok": true, "pending", "queued", "running", "retrying_since", "ticks", "last": {rc, seconds, deliveries, at}}`。
+- **Plane 侧**：工作区级 webhook（kappiee 工作区设置 → Webhooks，或 `tools/plane-webhook.py`），订阅"工作项"（`issue`）和"评论"（`issue_comment`）。Plane 会把所有项目的事件都发来，接收端按 `data.project` 只认配置里的项目。
+- **签名**：头 `X-Plane-Signature` = 用 webhook 密钥对请求体做 HMAC-SHA256 的十六进制摘要（Plane 签的是 `json.dumps(payload)`，发出的正是这串字节；接收端先比原始请求体，再比重新序列化的结果，均为常量时间比较）。缺失/不对 → 401，什么都不触发。其他头：`X-Plane-Event`（issue / issue_comment）、`X-Plane-Delivery`（每次投递的 UUID）。请求体：`{"event","action"(created/updated/deleted),"webhook_id","workspace_id","workspace_slug","data":{…,"project":<uuid>},"activity":{field,new_value,old_value,actor…}}`；删除事件的 `data` 只有 `id`（没有项目 → 202 忽略，由 cron 兜底）。
+- **触发逻辑**：配置项目的投递 → 200，3 s（`debounce_seconds`）内的投递合并成一次 tick；tick 运行期间又来的投递 → 它结束后再跑一次（正在跑的 tick 可能在变化之前就读过 Plane）。tick 命令就是 cron 脚本（`systemd-run --scope … cron/agentd-tick-lxc.sh`，在独立 scope 里跑，重启接收端不会杀掉正在跑的 tick）。脚本持 `flock -n -E 75`：锁被 cron/手工 tick 占着 → 退出码 75 → 每 15 s 重试，最长 2 min，之后交给下一个 cron tick。tick 本身的输出照旧进 `cron.log`/`agentd.log`。
+- **日志** `/var/log/plane-agentd/webhook.log`：每次投递一行（`delivery=<X-Plane-Delivery> event=issue/updated project=GWENT item=<uuid> decision=tick|202 ignored|401 bad signature|401 missing signature`），每次 tick 两行（`tick start (n deliveries: …)`、`tick done rc=0 in 12.3s` / `tick busy …, retry in 15s` / `giving up`）。Plane 侧的投递记录：`tools/plane-webhook.py logs <webhook id>`。
+- **查看**：`systemctl status plane-agentd-webhook`、`journalctl -u plane-agentd-webhook`、`curl -s http://10.77.10.249:8790/healthz`、`tail -f /var/log/plane-agentd/webhook.log`。
+- **轮换密钥**（在 oregon 上，kappiee 管理员会话，密钥不出进程、直接写进 Vault）：
+  ```bash
+  cd ~/.local/share/server-access-client && python3 -I agent-access.py --config https://nas.tail9531b.ts.net:8443/identity/agent.json exec \
+    --secret-env PLANE_KAPPIEE_PASSWORD=PLANE_KAPPIEE_PASSWORD --timeout 90 -- \
+    python3 -I /home/ubuntu/Documents/wjj/project/plane-agentd/tools/plane-webhook.py regenerate <webhook id>   # id: … plane-webhook.py list
+  ```
+  然后 LXC 上 `systemctl restart plane-agentd-webhook`（接收端只在启动时取一次密钥；轮换到重启之间的投递会 401，cron 兜底）。核对：`agent-access.py … exec --secret-env S=PLANE_WEBHOOK_SECRET -- python3 -c 'import os;print(len(os.environ["S"]))'`。
+- **停用**：只停接收端 `systemctl disable --now plane-agentd-webhook`（Plane 投递会失败并重试，多次失败后 Plane 自动停用该 webhook 并给管理员发邮件）；连 Plane 侧一起停：`plane-webhook.py patch <id> is_active=false`。cron 不受影响。
+- **通知**：配置里的 `notify: {kind: none}` 是钩子，核心每次改状态都调用 `Agentd.notify()`，目前什么都不做（没有 ntfy 服务）。
+
 ## 文件
 | 路径 | 内容 |
 |---|---|
 | `state/agentd-state.json` | 每项目每工作项：轮次、线程 ID 与所在终端/执行器、线程轮数、各轮标签、已见评论、重试计数/下次重试、在途运行（handle、deadline） |
 | `<log_dir>/agentd.log`（默认 `state/`） | 每次 tick 的动作与错误 |
-| `state/heartbeat.json` | 最近一次 tick 的时间、在途运行、启动未确认的运行（`launching`）、本 tick 跳过的不可达终端（`down`）、错误；超过 10 分钟不更新 = agentd 没在跑 |
+| `state/heartbeat.json` | 最近一次 tick 的时间、在途运行、启动未确认的运行（`launching`）、本 tick 跳过的不可达终端（`down`）、没派出去的 Todo 项及原因（`skipped`：`[{project, item, terminal, reason}]`）、错误；超过 10 分钟不更新 = agentd 没在跑 |
+| `<log_dir>/webhook.log` | webhook 接收端：每次投递的决定、每次触发的 tick（见上节） |
 | `state/agentd.lock` | tick 互斥锁 |
 | `state/runs/<run_id>/` | `transport: local` 终端的运行目录：`prompt.md run.sh pid.txt started.txt exit.txt stderr.txt` + 执行器输出 |
 | oregon `/home/ubuntu/.gwent-board/agentd-runs/<run_id>/` | 远程 Linux 终端（`run_root`）：同上，另有 `launch.pid`（启动时的 `$!`，与 `pid.txt` 相同）；claude 输出 `out.json` |
@@ -76,7 +96,10 @@ Todo + 指派给终端用户 → agentd 选最小编号、终端有空位、串
 | 现象 | 原因 / 处理 |
 |---|---|
 | `no Plane token in the environment` / tick 报 `no Plane token` | 没在 `agent-access.py exec --secret-env …` 下运行，或键名不对；`check-config` 看 MISSING |
-| `skip: another tick holds state/agentd.lock` | 上一 tick 还在跑（win10 上传慢）；正常。持续出现则查是否有卡死的 agentd 进程 |
+| `skip: another tick holds state/agentd.lock` | 上一 tick 还在跑（win10 上传慢）；正常（`tick` 此时退出码 75）。持续出现则查是否有卡死的 agentd 进程 |
+| Todo 项一直不动、心跳看着空闲 | 看 `heartbeat.json` 的 `skipped`：`concurrency n/m (GW-x)` 槽位被谁占着；`serialize_group … held by …`；`busy_process codex (… not started by agentd)` = win10 上有不是 agentd 起的（或上一轮还没退干净的）codex.exe；`relay down`；`no route for assignee …` = 指派的用户不是终端。原因第一次出现时 `agentd.log`/`cron.log` 有一行 `GW-n not dispatched (<终端>): <原因>` |
+| `webhook.log` 里 `decision=401` | 签名不对：Plane 侧密钥轮换后接收端没重启，或不是 Plane 发的。`systemctl restart plane-agentd-webhook` |
+| Plane 建 webhook 报 "The webhook URL is not allowed…" | Plane 的 SSRF 防护拒绝内网地址：Plane api/worker 环境需 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`（design §10） |
 | `[worker] 第 k 轮失败：类型=crash（临时性）…重试 n/N` | 网络/中继/429/5xx：按 `backoff_minutes` 自动重试，续原线程；超过 `transient_max` 转 Waiting |
 | `类型=timeout` | 超过 `timeout_hours`（或 `budget:2h` 标签）；进程树已结束，转 Waiting。看运行目录日志决定拆分任务或加预算 |
 | `类型=crash`（非临时）且是续线程 | 自动在新线程重跑一次（附交接摘要）；再失败转 Waiting |
@@ -100,6 +123,13 @@ Todo + 指派给终端用户 → agentd 选最小编号、终端有空位、串
 3. oregon 恢复 cron：`crontab ~/.gwent-board/crontab.backup-20261021-pad11`（即 `*/2 * * * * /home/ubuntu/Documents/wjj/project/plane-agentd/cron/agentd-tick.sh`）。`cron/agentd-tick.sh` 用 `config/agentd.oregon.yaml`（`state_dir: ~/.gwent-board/agentd`，日志 `~/.gwent-board/agentd/agentd.log`、`~/.gwent-board/agentd-cron.log`），与 LXC 配置只差路径。
 4. 看 oregon 的 `~/.gwent-board/agentd/heartbeat.json` 更新。再切回 LXC = 反过来做一遍（docs/deploy-lxc.md §5）。
 
+## 上线记录（2026-10-21，PAD-7：webhook 接收端）
+- 13:25 LXC 上 `plane-agentd-webhook` 启用（`6dc7e72`），cron 不变。**Plane 侧 webhook 未建成**：Plane 3.3.3 对 `http://10.77.10.249:8790/plane` 返回 400 "The webhook URL is not allowed. Provide a publicly reachable HTTP or HTTPS URL."（SSRF 防护拒绝内网地址，见 design §10）；需要在 Plane 的 api/worker 环境加 `WEBHOOK_ALLOWED_IPS=10.77.10.249/32`，之后按 deploy-lxc §8 第 2–5 步建 webhook。在此之前 Vault 里的 `PLANE_WEBHOOK_SECRET` 是临时随机值（`plane_wh_interim_…`），`plane-webhook.py create` 会用 Plane 生成的密钥覆盖它。
+- 验收用的是在 LXC 上按 Plane 格式签名的合成投递（`/root/lxc_send.sh good|bad|missing|other`）：错签名、缺签名 → 401，不触发；别的项目 → 202；正确签名 → 200，3 s 后 tick 开始。tick 运行中又来一条 → 结束后补跑一次（13:27 两条投递：224 s 的 tick——收尾 GW-15、在 win10 启动 GW-5——之后接着 24 s 的补跑）；那段时间 cron 的 tick 撞锁立即退出，cron 本身照常每 2 分钟触发。
+- 冒烟 GW-17（oregon claude-code）：建项 13:43:15.8 → 合成投递 13:43:41（经 oregon→LXC 中继发出，人为多了约 25 s）→ tick 开始 13:43:44 → `[worker] 第 1 轮开始` 13:44:56 → `[review] ok` 13:47:54，PASS 并移到 Done。**投递 → tick 开始 = 3 s；tick 开始 → 开始评论 = 72 s**（这一 tick 先 poll win10 上在途的 GW-5，再经中继启动 oregon；同期 cron 的启动 tick 也要 70–77 s）。真实 Plane 投递约 1 s 到达时，建项 → 开始评论预计约 75 s，而只靠 cron 是平均约 60 s 等待 + 同样的 tick 时长。≤10 s 的目标在"开始评论"这个口径上达不到：瓶颈是中继调用（每次约 10 s，vault + Warpgate SSH）和启动流程，不是触发方式。
+- GW-16（第一次冒烟）：webhook 触发的 tick 里 LXC→中继报 `access-hub: config_private_transport_failed`（LXC 经 tailnet 取 `nas…/identity/agent.json` 15 s 超时；13:38 的 cron tick 也撞上一次），启动失败；下一 cron tick 探测无运行目录 → `GW-16-1-r2` 重新启动，PASS（防重复启动机制按设计工作）。
+- 重启：tick 运行中 `systemctl restart plane-agentd-webhook`，tick（在 `systemd-run --scope` 里）没被杀、照常结束（heartbeat 13:50:10，errors=[]）；接收端约 19 s 后重新监听（取 vault 密钥 + 启动）。
+
 ## 切换记录（2026-10-21，PAD-11：调度器迁到 LXC agentd-01）
 - 代码：防重复启动（`launching` 标记 + 探测接管/换目录重启）与"中继不通的终端本 tick 跳过"随本次一起上线（4f45d36）；LXC 用仓库里的 `config/agentd.yaml`，oregon 回滚用 `config/agentd.oregon.yaml`。
 - 切换前 LXC 手工 `tick --once`（oregon cron 仍在跑，Plane 上无 Todo 项）：空闲、无错误；LXC 经 helper 探测 win10（`codex` 计数）与经中继探测 oregon 运行目录均正常。