moai-lane-watchdog

概述

moai-lane-watchdog 是 moai-adk 项目中的一个技能，面向在工厂车道上运行的会话（moai cc / moai glm / moai codex），执行一轮停滞看门狗巡检。其规则依据来自 .claude/rules/moai/workflow/auto-semantics.md，技能正文是可执行流程。在会话首次巡检前，还需完整阅读 .claude/rules/moai/workflow/factory-dispatch.md 与 cross-session-messaging.md（Codex 专属项目对应 .moai/policies/ 下的同文件）。

主要能力与流程

0a. 续签卡片租约

每轮第一步通过 moai factory renew <card-id> --json 续签本车道持有的卡片；从 stdout 的 JSON 读取 renewed、refused-expired、refused-not-holder 或 error，结果记入快照字段 renew_result。续签被拒不会终止本轮，也不在本轮内重试；若本车道卡片均已合并就绪、挂起或等待串行槽位，则本轮不续签，沿用上次结果。

1. 测量进度

三个通道：

• HEAD：车道自身工作树中的 git rev-parse --short HEAD；
• 证据修改时间：.moai/reports/<card-id>/ 与当前 SPEC 的 progress.md 中最新的 mtime；
• 集成窗口状态：moai integration status。

与 .moai/state/watchdog/<card-id>.json 中的上一快照（字段：observed_at、head_sha、evidence_mtime_max、window_state、renew_result、last_change_at）比对。三个通道自上一快照以来全部未变，且距 last_change_at 记录的最后一次变化已超过 N 分钟时，才判为停滞；N 默认 15 分钟，为每次调用参数而非配置项。无上一快照时，记录新快照并把 last_change_at 设为其自身 observed_at，不给出停滞结论（首次观察失败开放）。任一通道变化即视为进展，结束本轮并输出一行状态；但若车道停驻于委派任务，则改由委派产物决定。

2. 原因分类

• awaited-judgment：车道停在需要判断之处（关口、裁决、选择），未收到回复；
• blocked-by：卡片等待前序卡片，前序落地状态是未决问题；
• shell-error：车道因未裁决的命令失败（非零退出且无处置记录）而停止；
• accidental-stop：会话在卡片中途死亡或被中断（如 429 结束轮次），且无有意停止记录；
• awaited-delegate：车道停驻于委派工作（生成代理报告、后台运行完成），报告或通知未到。

未检测到停滞或检测到进展则结束本轮。

3. 应用补救

• awaited-judgment：按顺序执行决策阶梯：①磁盘证据（审计裁决文件、进度记录、计划审计裁决、证据路径）——显示继续则恢复，显示不可继续则记录等待，不可读或缺失则进入下一步；②决策板 moai decision read --scope card:<id>——已有裁决则遵循，裁决为等待则写显式等待记录，空板则继续；③审计交叉——执行一个 moai MCP 审计工具（codex_audit、glm_audit、claude_audit 或 audit_multi），肯定则按裁决继续，否定则失败关闭并升级，工具缺失或结论不明则进入下一步；④jev_ask——仅在 workflow.jev.enabled 为 true 时使用，用于有界的继续/重试/等待判断，不用于完成、合并或队列结果；⑤负责人会话——最后手段，记录显式等待后让出。最后写入一条决策记录。
• blocked-by：直接读取阻塞前序的磁盘证据；显示前序已落地则恢复，否则记录含原因、前序 id、复查点的显式等待。前序被丢弃时，等待记录中指明队列关系移除动词作为操作者出口，但本技能不执行队列变更。
• shell-error：区分瞬时错误（网络抖动、锁竞争、时序不稳定）与确定性错误（远端缺失、坏引用、用法错误）。瞬时错误最多重试 3 次并记录；耗尽后输出结构化阻塞报告。确定性错误零重试，直接输出带原始错误文本的结构化阻塞报告。
• accidental-stop：通过检查点返回恢复，使用带工作树锚定 Block 0（git rev-parse --show-toplevel）的会话交接恢复消息，从卡片进度记录中最后检查点继续，绝不从零重启卡片。
• awaited-delegate：对照委派记录读取磁盘上的委派产物（要求写入的产物、输出文件、提交）。产物存在且一致则恢复并消费，不等待报告；产物缺失或部分且委派方已结束，则带部分状态重新委派，或仅在仍是活跃同伴时用 SendMessage 恢复；已用 TaskStop 停止的同伴不可按名寻址，以免唤醒为无主写入者。产物缺失但证据仍在变化则记录等待，复查点为下次 cron 触发；缺失且无结束迹象、连续两次触发证据未变，则输出结构化阻塞，不再第三次等待。

4. 决策板协议

磁盘决策板为唯一事实来源（SSOT），仅追加、每行一条记录，不重写历史。视图用运行器原生任务工具渲染（Claude 运行器用 TaskCreate/TaskUpdate，codex 用 update_plan），但裁决只从磁盘读取；视图不是 SSOT，长篇计划文档也不是决策板。Codex 第 ⑤ 步无会话消息工具，跨运行器通知走磁盘队列委派通道，等待原因仍写磁盘。

5. 决策记录

每次自主关口转换和每次经阶梯解决的判断，在磁盘板上写一行可 grep 的记录：

decision record: decided_by=<runner+role> evidence_refs=<paths+verdict-ids> ladder_path=<step>

decided_by 注明裁决运行器与角色，evidence_refs 注明所依据的产物路径与裁决 id，ladder_path 注明阶梯步骤（①–⑤）或解决它的关口行。

6. 组合边界

队列级拾取决策（排除无关或阻塞卡片）属于队列界面所有者；本看门狗对队列只读：读取证据与状态界面，零队列变更，从不拾取、丢弃、编辑或解除关联任何内容。

7. 输出形态

每轮以且仅以下一种结束：

• resumed：检测到进展或判断已解决，说明步骤并引用决策记录行；
• explicit wait：给出等待记录行与复查点，结束本轮，不做空转；
• structured blocker：确定性失败或重试耗尽，给出原始错误、尝试内容、读取证据与待决事项，返回编排会话，不越过重试上限，不向任何人提问。

硬性边界

• 从不向操作者提问，从不代答审批关口；保留集关口（环境不可行、操作者持有、不可逆的外部共享操作）只复查并让出；
• 队列只读；
• 每个树一个写入者：只写自己的快照、证据记录与磁盘决策板；
• 验证为车道本地，无后台负载；
• 不依赖钩子：仅 awaken-tick；触发它的调度器是车道常驻复查 cron，本技能是其提示词而非所有者。

适用场景

适用于 moai-adk 工厂车道上运行卡片会话的自动化停滞检测与处置，尤其是需要在不打扰操作者的前提下自主解决判断关口、处理阻塞与命令失败、恢复意外中断、检查委派产物等场景。

限制

• 每轮只处理一个车道会话，N 分钟阈值为调用参数；
• 保留集关口永不满足，只可复查后让出；
• 不执行队列变更，不负责队列级拾取决策；
• 依赖项目中的规则文件、moai 命令行与 MCP 审计工具，这些不可用时按阶梯降级；
• 具体 cron 配置与部署方式资料未提供。