[设计] 明确角色协作协议：持久化 Handoff、咨询分离、打回续接与个人代理优先 #2175

Written-by: Codex

定位与关联

将已确认的角色协作边界落成可实施的接口契约设计。关联 #2170（独立个人代理）、#2171（Project 与角色治理）。
这是设计收敛记录，不是自动领取/立即部署指令；不打断现有前端执行。
与 #55、#1775 等已有交接/路由工作衔接：复用持久化记录、角色池、领取凭据与 Effects/outbox，不另建调度器。本单补齐交付分支 delivery/ai-centric-development-service 的对外表达、咨询分离和恢复语义；不能把分支已有能力误报为主仓 main 已有能力。

已确认的设计

1. 咨询与交接是不同协议

• consultation.ask / reply / get：请求意见、解释或裁定；保留关联上下文和持久化问答，不改变任务池归属或任务主动权，不因为普通询问创建 Task。
• handoff.offer / accept / get / list：显式转移下一步推进责任，有持久化契约和接手凭据。
• 角色定义是稳定对象；收发消息、交接的是其执行实例。以上是语义接口名，实施时映射既有 service/API，避免重复入口。
• 现有向 Chief 咨询使用 conversation-handoff/v1，需在接口、事件类型、文档中与任务交接分离；保留旧记录可读性和必要兼容，不把旧咨询误迁移为任务移交。

2. handoff.offer：持久化后进入目标池

契约至少包含：

• 唯一 handoffId、协议版本、幂等 requestId；
• projectId、taskId、当前执行轮次、状态/代次；
• 来源角色与执行实例、目标角色，实际接手实例在 accept 时记录；
• 类型：正常下传、打回、转交、提交 Chief 裁定；
• 已完成事项、交接原因、目标下一步要求；
• 候选代码版本、修改记录、测试结果、产物等结构化引用与证据；
• 来源执行记录和目标角色既往 Task-role Session 的上下文引用。目标 Session 引用由服务按权限解析，不允许调用方伪造或读取他人私有上下文。

成功只表示契约、目标池与待派发动作已持久化，不代表已接手/执行/完成。沿用同一持久化提交边界、幂等与代次校验，提交成功后才允许派发。

3. handoff.accept：明确主动权归属

• offer 前：来源 Bot 持有主动权。
• offer 成功后：来源交出主动权，由目标任务池托管，等待领取；来源执行必须确认安全退出，不能双写。
• accept 成功后：目标执行实例取得推进责任，记录实例、时间、领取凭据。
• 验证目标身份、版本/代次、权限、并发及来源执行释放证明。
• 接收方可执行，也可打回、转交或请 Chief 裁定；这些决定产生关联的新交接契约，保留历史。
• 派发失败、等待超时保持可查询、可恢复，由重试或 Chief 处理，不能默认为对方接手。

4. 查询与状态

handoff.get/list 返回契约、接手凭据、当前状态和事件历史，至少区分待接手、已接手、已处理、已撤销/失效。

• 已处理只代表本轮交接处理结束，并关联后续交接或裁定；不等于 Task 完成。Task 关闭仍须 Chief 裁定。
• 派发失败、执行超时等异常独立表达阶段、原因及恢复信息，不能用一个 failed 混淆主动权。
• 幂等重试返回原契约；重启/响应丢失恢复原记录，不重复创建任务或授予执行权。
• 撤销/失效只能通过受权限与版本约束的状态变更产生；审计保留，不凭状态名称新增任意操作权限。

5. 打回必须恢复原角色上下文

Dev → Tester → 打回 Dev：恢复 Dev 之前处理同一任务的逻辑 Session 和可恢复 SDK 会话，读取本次交接增量；不能复制 Tester 全量对话替代 Dev 上下文。
新 Attempt/进程不等于新会话。当前已有 Task-role 逻辑 Session、backendSessionId 与 continuedFrom 等恢复基础；需补齐绑定变更等异常语义。
无法 resume 时明确报告恢复问题，保留历史与恢复依据；不得静默开启无历史的新 Session 并声称已经恢复。资源/Harness 等不兼容变更的迁移策略后续明确，不在本单假定可跨 SDK 原样续接。

6. 联系用户优先联系个人代理

需要用户输入时优先联系该用户参与项目的个人代理，在其有效授权内答复/处理；确需本人或超出授权才升级给用户。保留安全模式/值守模式边界，不能绕过 Owner 关闭项目的二次确认。
不要求角色间消息绕行个人代理；Chief/Dev/Reviewer/Tester 仍可直接协作。与 #2170 的多代理参与和外接代理能力衔接，不能宣称外接代理已验证可用；多代理具体收件选择仍需确定。

验收与测试

• 咨询往返不创建任务、不改变当前执行权；旧咨询记录兼容读取。
• Dev → Tester → 打回 Dev，断言恢复 Dev 原会话并获得交接增量，区分逻辑 Session、SDK 会话和新 Attempt。
• resume 不可用时显式报告，不静默清空上下文。
• offer 前后、持久化前后、派发/accept 响应丢失、重启、重复调用与过期回调注入：一个逻辑交接，无双持有/重复执行授权。
• 待接手与已接手的查询结果、角色权限、跨项目隔离、来源释放证明、非法/重复 accept。
• 打回/转交/提交 Chief 形成可追溯链，交接已处理不误标 Task 完成。
• 联系个人代理的授权路径，以及必须本人确认的升级路径。
• 测试通过与真实任务验证分别记录；不声称外部系统无条件 exactly-once。
• 同步项目长期记忆、架构/子系统文档、接口参考、使用示例与变更记录，描述现状、目标及兼容迁移。

范围

本单聚焦角色协作接口，不继续扩展完整 Task 模型，不重建 control-plane，不改固定工作流替代 handoff，不强制新增人工准入审批。