| name | task-watchdog |
| version | 1.0.0 |
| description | 任务锁与超时监控系统。外部文件承载任务状态，不污染 agent 上下文，纯靠 heartbeat + GRACE 判断，不发即时告警。 |
Task Watchdog
核心概念
Lock 文件是任务的外部状态载体，放于 ~/.openclaw/agents/{agent_id}/locks/：
active/ — 正在执行的任务archive/YYYY-MM-DD/ — 归档（done / abandoned / timeout）
两个时间字段，职责不同：
last_heartbeat — lock-self-check 更新（纯心跳维持，不说明任务有进展）
last_progress — lock-update --progress 时更新（标记真实进展）
状态判断（用 last_progress，不看 last_heartbeat）：
✅ 正常 session 存在，last_progress 正常
⚠️ SESSION_DEAD session 已消失
⚠️ STALLED session 存在，但 last_progress 超 GRACE×3
⚠️ HEARTBEAT_DELAY 心跳延迟
🚫 abandoned session 消失 + last_progress 超 GRACE×3
📦 done 任务完成，立即归档
脚本
| 脚本 | 用途 |
|---|
lock-create.sh | 创建 lock → active/ |
lock-update.sh | 更新 heartbeat；--progress 时同时更新 last_progress |
lock-done.sh | 标记完成 → 归档 |
lock-status.sh | 查询状态 |
scan-locks.sh | 扫描 active/，异常归档 |
lock-archive.sh | 归档N天前 / 清理N天前 / 统计 |
lock-report.sh | 查看所有活跃任务状态 |
lock-self-check.sh | Agent 自检：更新心跳 + 处理 abandoned |
推荐用法
关键节点调用：
任务开始 → lock-create
每个关键步骤完成 → lock-update --progress "X完成，开始Y"
任务全部完成 → lock-done
HEARTBEAT 触发时调用自检：
收到心跳轮询时
→ 调用 lock-self-check.sh
→ 自动完成：
无活跃任务 → 无输出，agent 回复 HEARTBEAT_OK
owner session 存活 → 只更新 last_heartbeat
owner session 已死 → 接管任务（更新 session_id + last_heartbeat）
→ 无需判断逻辑，脚本自动处理
设计目标
任务续做保障系统，不是即时告警系统：
- 中断后 lock 留在 active/，Supervisor 扫描归档
- 自检机制让 agent 自动继续被中断的任务
- 定期报告让负责人知道哪些任务需要接管或放弃
常用命令
./lock-self-check.sh --agent-id xxx --session-id xxx
./lock-report.sh
./lock-archive.sh --list
./lock-archive.sh --archive-days 7
./lock-archive.sh --cleanup-days 30
