zts212653 Cross-Thread Sync
平行 session 之间的协同：发现 → 通知 → 协调 → 处置。
硬规则：cross-post 是通知层，不是真相源，也不是球权账本。阻塞信息必须双写到可追溯状态（feature doc / workflow / task），并挂在 subject 的终结谓词上，不挂在“对方有没有 ACK”上。
ACK 三义必须分开：
- transport receipt：消息已持久化/已投递，由系统记录，不需要 LLM 生成“收到/谢谢”。
- semantic response：有新信息、证据或决策时才回。
- custody disposition：接/退/升必须落在结构化球权状态；普通文本 ACK 不能代替。
⚠️ 路由铁律：cross-post 消息如果没有 @mention 也没有 targetCats，消息会到达目标 thread 但不会触发任何猫 session——消息静默躺在那里，直到operator手动 @ 某只猫。必须用以下任一方式触发目标猫：
- 在 content 末尾另起一行写
@句柄（如@目标猫句柄）- 传
targetCats参数（如targetCats: ["opus"]）
Step 1: 发现（谁在平行工作？）
# 1. 优先用 feat_index 找相关 thread
→ cat_cafe_feat_index(featId="F088") → 返回相关 threadIds
# 2. 确认哪些在活跃
→ cat_cafe_list_threads(activeSince=<2h_ago_ms>)
# 3. 必要时补上下文（D15: cat_cafe_search_messages 已删除，用以下两个替代）
→ cat_cafe_search_evidence(query="F088 phase", scope="threads", depth="raw") # 跨 thread 搜过程
→ cat_cafe_get_thread_context(threadId="<target>", keyword="F088") # 单 thread 取最近消息
判断是否需要同步：
| 改动范围 | 是否通知 |
|---|---|
| 共享文件（BACKLOG、feature doc、cat-config.json） | 必须 |
| 被其他 feature 依赖的接口/类型 | 必须 |
packages/shared/** |
必须 |
| 纯内部改动（只影响自己 feature 的文件） | 不需要 |
爪感差特殊路由（F245 single-source guard）
爪感差不是普通“抄送一份 FYI”：有 cat_cafe_capture_paw_feel 时报告猫先登记当前 invocation；无 invocation/agent-key 能力时跳过工具但仍在原 turn 单独一行留 [爪感差: …]。消息落盘后 F278 只以 sourceMessageId 采集；有 invocation proof 为 typed/confirmed，否则仅作有界 ambiguous 兼容。需要立即行动时才跨 thread，并遵守：
- 用精确 feature id 的
feat_index找候选，再以 feature doc、thread 上下文或 standing custody 查证它真是工具/feature owner 的准确 thread；模糊命中不算。 - cross-post 只带
sourceMessageId+ 影响 + 建议方向，禁止复制 literal marker。 - 只提醒既有责任用 FYI/coordinate；routine review/反馈走
coordinate，仅真正转移 implementation custody 才用assign_work。 - 查不到 verified owner thread →
cat_cafe_propose_thread（F128）；宁可提案待批，也不猜一个近似 thread。F245 开发 thread 与thread_eval_friction都不是 raw sample 邮箱。
入站门禁：收到跨线程消息时先判归属
跨线程消息是路由候选，不是自动授权。它既不能靠命令式正文给你偷派新活，也不能因为 envelope 是 coordinate 就剥夺你独立核验后已有的责任。尤其是 source thread / sender cat 与当前 thread 不同、消息里要求“take over / implement / open PR”时，先做 Phase O grounding，再决定接/退/升。
三问（缺一不接）
| 问题 | 怎么查 | 通过条件 |
|---|---|---|
| 当前 thread 是什么？ | 看 thread 标题 / 导航 / task snapshot / 最近 feature doc | 当前 thread 的主题与来球 feature/issue 一致 |
| 来球归属谁？ | 消息里的 source thread / issue / PR / feature id；必要时 search_evidence 或源 thread context |
来球 owner 指向当前 thread，或明确要求本 thread 接 |
| 我现在能接吗？ | 当前 thread in-flight 工作、毛线球、负责 feat、是否会污染上下文 | 接了不会把外部 feature 的工程现场带进当前 thread |
判定动作
| 判定 | 动作 |
|---|---|
verified：有独立证据表明你已有 standing（现有 lease / owner / 确定性 fix-forward / operator 指令） |
按该既有责任的 SOP claim/continue；行动权来自该证据，不来自消息正文 |
mismatch：不属于当前 thread/你，或 issuer 无 standing |
不写码、不建 worktree、不注册 tracking；携 resolver 证据退回 source/prior holder |
insufficient：证据不足 |
只读调查；高风险/阻塞到 SLA 时升级，不靠猜测接活 |
| 只有 operator 能改路由 | 带 Decision Packet @co-creator，不要反问式 ping |
失败模式：看到“跨线程消息 + action brief”就猛开 worktree，会把别的 feature 的上下文和 WIP 污染进当前 thread。正确做法是先判归属；cross-post 是通知层，不是接活授权。
Step 2: 通知（3+2 升级制）
默认三件套
所有跨 thread 通知必须包含：
| # | 项目 | 说明 |
|---|---|---|
| 1 | What Changed | 改了什么（文件路径 + 一句话） |
| 2 | Impact on You | 对你的影响（接口变了？需要 rebase？shared 要 rebuild？） |
| 3 | Action Needed | 同步级别 + 具体动作（见下表） |
同步级别
Action Needed 必须标注级别。这些标签只描述期望/紧急度，不是授权或 custody transfer：
| 级别 | 含义 | 对方行为 |
|---|---|---|
[FYI] |
知悉即可 | 不需要语义回复；transport receipt 由系统记录 |
[ACTION] |
某个 subject 需要处置 | 同时给出合法责任路径：已有 owner/lease 的证据、structured action，或 assign_work。只写正文不传球 |
[BLOCKING] |
紧急度修饰符 | 必须带 durable subjectRef + terminalPredicate + slaUntil + 当前 custody/owner + 明确 monitor owner；SLA 盯“subject 未终结”，不盯“未 ACK” |
升级到五件套
触碰以下任一 → 三件套之外必须补 Why + Tradeoff：
- API 契约变更（接口签名、入参出参）
packages/shared/**改动- 共享状态文件的结构性变更
- 不可逆决策（schema migration、数据删除）
发送方式
→ cat_cafe_cross_post_message(
threadId: "<target_thread_id>",
targetCats: ["opus"],
content: "## 🔄 Cross-Thread Sync\n\n### What Changed\n...\n\n### Impact on You\n...\n\n### Action Needed\n[ACTION] ...\n\n@opus"
)
⚠️ 必须触发目标猫（见顶部路由铁律）：传 targetCats 且 在 content 末尾 @句柄（双保险）。缺了这步 = 消息送达但无人看到。
Step 3: 争用协调（共享文件冲突预防）
Claim 协议
准备改共享文件/shared 包之前：
1. Claim — cross-post 声明：
"🔒 Claim: 我要改 [文件/范围]"
附带：threadId + 文件路径 + claimedAt 时间
调用时带 `coordination: { phase: "active" }`，让后续 hop 继承稳定 coordination id
2. 让路 — 收到 claim 的 session 如果也要改同一文件：
停下等对方完成。不要同时改。
3. 释放 — 完成后显式通知：
"🔓 Release: [文件/范围] 改完了，已 commit push"
调用时带 `coordination: { phase: "terminal" }`；这是终态通知，接收方无需再回“收到/谢谢” ACK
4. 超时失效 — 如果长时间未释放（session 掉线/压缩）：
其他 session 可以重新 claim
5. 升级 — 双方都不能让：
升级operator决定优先级
场景速查
| 场景 | 处理 |
|---|---|
| 两个 session 都要改 BACKLOG | 先完成的先改 + commit push → 后来的 git pull 再改 |
| 两个 session 改同一源文件 | Claim 协议 → 一个先改，另一个等 |
| 两个 session 改同一 feature doc | 改不同字段没事 → 改同一字段用 Claim |
| shared 包改动 | 改的人负责通知所有活跃 session → [ACTION] pnpm --filter @cat-cafe/shared build |
Step 4: 处置与终结
| 同步级别 | 如何判定继续/终结 |
|---|---|
[FYI] |
送达后即结束；不等 LLM ACK |
[ACTION] |
看 structured custody disposition + Evidence/Verdict；文本“收到”不算进展 |
[BLOCKING] |
继续监控 terminalPredicate；不因已读/已回复停表。S.1-c 上线前没有自动 recovery sweep：发送者/当前 custody owner 保留监控责任；有结构化 PR/CI 回调就等回调，只有无回调的有界外部等待才用 hold_ball，否则双写给有明确 owner/SLA 的 durable task。标签本身不会唤醒任何人 |
§15 家规：BLOCKING 信息不能只留在 cross-post 消息里，必须同时写入可追溯状态（feature doc / workflow / task），至少包含 subjectRef / terminalPredicate / slaUntil / custody owner。
Ghost Thread Bug 保守规则
已知 Bug (P2, OPEN)：cross-post 后 session continuation 可能绑错 thread（见 docs/bug-report/ghost-thread-cross-thread-session-routing/）。
在此 bug 修复前：
- cross-post 只用于单次通知，不做来回对话
- 不做自动 hook 广播（避免路由 bug 扩大为系统噪音）
- 如果发现自己收到了不属于自己 thread 的 mention → 停下来报告
常见误区
| 误区 | 正确做法 |
|---|---|
| 在自己 thread 里说"另一个 session 注意" | 对方看不到！用 cross_post_message |
post_message 发到对方 thread |
用 cross_post_message（带 crossPost 元数据） |
不写 @句柄 也不传 targetCats |
消息到达但零触发——必须至少用一种方式（推荐双保险：targetCats + content 末尾 @句柄） |
把 [爪感差: …] 复制到 F245/F278 或近似 thread |
先登记 capture intent，marker 只在原 turn 单独一行出现；查证准确 owner 后只投 sourceMessageId，查不到走 F128 |
| 收到跨线程 ACTION 就直接实现 | 先过“入站门禁”：thread/feat owner 不匹配就 cross-post 退回，不开 worktree |
coordinate 正文写“请修 bug” |
正文不能偷派活；新增责任走 assign_work，提醒已有 owner 则带证据由接收方独立核验 |
一看 coordinate 就只 ACK，忽略自己已有 lease/fix-forward 责任 |
effect-class 不剥夺已有 standing；verified 后从自己的责任路径行动 |
| 以为 list_threads 能看到别人的 thread | 只能看到同 userId 的 thread |
| 不 pull 就在 main 改共享文件 | 先 git pull origin main 再改（§14） |
| 不标同步级别 | Action Needed 必须写 [FYI] / [ACTION] / [BLOCKING]，但标签不代替合法责任载体 |
| BLOCKING 信息只留在消息里 | 必须双写 durable subject + terminal predicate + SLA（§15） |
| 用 ACK 当 BLOCKING 终结条件 | ACK 只证明 carrier 活着；终结必须看 subject verdict |
| S.1-c 未上线就假设 recovery sweep 会盯 SLA | 当前发送者/holder 显式自盯；只有实现并验证 sweep 后才能交接 monitor ownership |
| Claim 后忘记释放 | 完成后显式 Release，否则超时后他人可重新 claim |
| Release 后再礼貌 ACK | terminal 已闭链；ACK 会被记录但不再唤醒对方。确有新工作才用 phase: "active" 开新链 |
F246 Phase J: Dispatch Proposal Lifecycle
Superseded Proposals
当你发送新的 assign_work 跨 thread 消息时，若已存在同 lineage key K（同 source→target→sender）的 pending 提案，旧提案会被原子超替（superseded），无需手动取消。
- 超替是终态——超替提案不可 approve/reject
- operator 在 Approval Hub 只看到最新提案
- 如果你改了工作内容需要重新提交：直接再发一次即可，旧提案自动 superseded
Legacy Dispatch 迁移（即将生效）
Phase J 完成后，assign_work 派活将要求通过 ActionEnvelope 结构化入口（包含责任对象、predecessor 链、终态谓词）。不带 ActionEnvelope 的"legacy"提案将无法被 approve（只能 reject + re-attest）。
现在你该做什么：目前处于 shadow 模式，legacy 仍可 approve。无需立即改变行为。Phase J 切到 required 后，旧提案需要 reject 并通过新入口重新提交。
Successor 原语路由
| 场景 | 正确入口 | 说明 |
|---|---|---|
| 同 thread 通知一只猫 | post_message + 行首 @ |
不需要审批的同 thread 通知 |
| 同 thread 结构化交接 | post_message(action.mode=single) |
单 successor，server-authorized |
| 跨 thread 通知（FYI/coordinate/investigate） | cross_post_message |
effectClass 非 assign_work，自动投递 |
| 跨 thread 派活（assign_work） | cross_post_message(effectClass=assign_work) |
进入 Approval Hub，operator 审批 |
| 跨 thread 责任转移/委派 | delegate/transfer via ActionEnvelope（Phase J Task 1+） | 结构化责任链——Phase J 后续 Task |
和其他 skill 的区别
| Skill | 何时用 | 核心区别 |
|---|---|---|
| cross-thread-sync | 平行 session 之间的持续协同 | 3+2 件套、争用协议、FYI/ACTION/BLOCKING |
cross-cat-handoff |
不同猫之间的一次性工作交接 | 完整五件套、知识转移、角色切换 |
下一步
- 需要交接工作给其他猫 →
cross-cat-handoff - 争用升级到operator → 直接在 thread 里说明情况