坑速查：症状 → 真因
本页由 site/gen.mjs 从仓内 docs/USAGE.md §6 生成，勿手改
坑表的唯一真相是 USAGE 的坑速查表；接完线拿它自查一遍。
| 症状 | 真因 |
|---|---|
| 模型第一次调工具被拒，第二次同参重试就过了 | 正常行为——「拒绝即激活」。看 Retryable(err) 是不是 true |
| 同一个工具被反复拒，每次理由都不同 | 你没用 guardset，链在第一个拒绝处收口了 |
| 重启后陈旧快照写畅通无阻 | SeedFromStore 没回灌，SeqGate 重启即空 |
| 落库失败后某个环节再也提交不了终态 | commitgate 的 Release 没调 |
| 压实后界面还显示「上下文紧张」 | 没显式 Meter.Shrink 把账改回来 |
| 净移除量对不上，方向是「看起来更省了」 | 用了 GrossRemovedTokens，要减应该用 NetRemovedTokens |
| 摘要写进消息的指纹能被跨库比对 | 占位暴露了全量摘要，应该只给 12 位前缀 |
| 模型从未见过某张图片，之后却在引用它 | offload 首轮就替换了，或落盘失败仍被标记 |
| 会话一长跑内存就涨、收口卡住 | delta.Pacer 被做成了长生命周期对象，应每环节新建 |
| 一个卡死会话把所有会话陪葬 | 用了 Drain 而非 DrainSession |
| 挂起态莫名其妙消失 | 落列绕过了 pending.ColumnValue |
| 超大模型输出居然「解析成功」且置信度不低 | 命中过截断式上限失效的坑，现已 fail-closed；若你 fork 了本仓请确认走的是 ErrNotReport 分支 |
| SSE 进度条停在中间态 | 正常——总线有损，靠 DB 回放游标补达；先确认发布路径是「先落库再广播」 |
| 判定环拒绝后 host.<tool>() 仍然执行 | ptc.Options.Stages 没传 |
| 工具重试把一次副作用变成两次 | 只看了 Retryable，没看 SafeToResubmit |
make check 报域词污染 | 领域资产漏进内核了——它该在宿主仓 |
| 加了个新包门禁立刻红 | 没在 architecture-policy.yaml 的 modules 段登记 |
| 本地全绿但 CI 报 checksum mismatch | 见 §5 的 tag 重写 / 缓存回退两条 |
| 想临时停掉某条守卫，只能重启进程 | 你在用 guardset.Stage(set) 绑死了某一份——改用 guardset.Assembly，撤销 = Without + Swap（换整份，链不用重接） |
| 撤销某条守卫后，宿主以为降级生效了，实际没有 | Set.Without 对不存在的名字会报错（ErrUnknownGuard）；若你绕过了它去改 Set，那是两个真相 |