Enable SDK Reviewers to fetch trusted GitHub PR and build evidence within scoped resource permissions #2378

Written-by: Codex

目标分支与负责人

• 实现/PR 目标分支：delivery/ai-centric-development-service。
• Assignee：@zy95-12。
• 关联 Use role-bound GitHub App identities for SDK development, reviews and delivery reconciliation #2365（角色 App 身份、SDK GitHub 操作与候选/PR 回写）、Automatically enter the host merge flow after Reviewer approval of the current candidate #2331（审核通过后的受控合入）、Validate dependency readiness and distinguish environment blockers from code test failures #2334（环境准备/测试失败分类）、Reconcile proven execution exit with durable claim retirement before integration admission #2375（退出与 claim 退场）、Preserve continuation baseline and draft lineage when restarting cancelled delivery attempts #2377（草稿/基线续作）。
• 本条聚焦 Reviewer 的 GitHub 可达性和可信证据获取，不替代上述身份、绑定或恢复 Issue，不中断主会话开发。

用户报告与已核对事实

用户报告 OpenToday 的 SDK Reviewer 无法访问宿主外开的 PR #3/#4，只能对本地可见源码给出有限结论；需运维通过 input.publish 搬运 PR 元数据/build 说明，任务容易转为 awaiting-owner。

只读核对交付代码 8e47767（PR #2362 已合入）：

• project-harness-turn.js 的普通 Codex 角色配置 limited network、domains={}；该限制不只影响 Reviewer。CLI 本身具备工具执行能力，当前缺口在 FlyBot 授予的网络/认证/工具能力。
• SDK 配置清空 MCP servers/plugins；原生代理的 project_agent_github 工具不能据此认定已自动暴露给 SDK Reviewer。
• 宿主 project-github-read.js 已有 scoped PR/reviews/checks 查询与身份记录，可复用；部分读取是 bounded-first-page，不能把第一页当作完整门禁事实。
• 宿主审核门禁要求正式候选 SHA、干净的候选工作区、精确 SHA 的 Review 与匹配的实际测试证据。可见源码“未发现阻断”不等于外部 PR、build 或整体验收已通过。
• input.publish 是待处理输入/说明，不是可信 GitHub 查询回执或真实测试证据；操作员粘贴“CI 通过”也不能直接填入正式 evidence。
• 外开 PR 未关联当前 Attempt 是独立阻塞：联网可见 PR 不等于已认领候选/publicationBinding，仍需 Use role-bound GitHub App identities for SDK development, reviews and delivery reconciliation #2365。

本次未重放 PR #3/#4 的现场网络、角色配置及检查时间线；实现前须以当前基础提交做隔离最小复现，并区分现场报告、源码事实和实际 SDK 验证。

目标链路

正式认领外部 PR → 准备精确 SHA 源码 → Reviewer 自主查询 PR/检查并审阅 → 记录匹配候选的证据 → 进入 #2331 受控合入。

无需运维反复通过 input.publish 搬运可由系统获取的事实。能力不足应给出明确分类和恢复条件，由 Chief 决策，不默认升级等待 Owner。

实现范围

1. Reviewer 的获准 GitHub 访问能力

• 与 Use role-bound GitHub App identities for SDK development, reviews and delivery reconciliation #2365 共用角色绑定的 App installation 身份、短期凭据、最小权限、续期和审计；不能借个人 gh、Owner 或 ambient token。
• 支持 SDK 角色直接使用获准的 git/gh/API，或通过同契约的受权查询入口获取事实；宿主查询作为可用适配/受限资源的补充，不把 SDK 自主开发重新退化成每个动作都必须由宿主代做。
• 显式配置资源/角色所需 GitHub 网络访问或查询通道，核验实际 DNS、代理、连接和认证链。仅提供 Token 不算可用。
• 允许范围覆盖实际采用操作所需的 GitHub API/Git/对象下载路径；未授权目标仍拒绝，不全局开放网络或泛化 URL 代理。
• 私有仓库可达性、网络策略拒绝、凭据缺失/过期、App 权限不足及安装范围变化分别分类，不能统称 Review 失败/代码问题。
• 本地与 Docker、原生与 SDK 遵守相同的身份/证据契约；不能以原生工具存在代替 SDK 已接通。
• 保留 Chief 与 receipt-only correction 等既有专用权限边界，不因开放正常 Reviewer 查询而给纠错轮次或其它角色额外工具/凭据权限。

2. 精确候选源码与只读工作区

• Reviewer 开始前明确当前 Project/Task/Attempt、PR、head/base 仓库与分支、完整 candidate/head SHA，以及源码是否已正式关联。
• 缺少源码对象时，复用宿主的已验证对象传输/工作区物化，或在登记的独立可写 scratch 中获取所需对象；不能要求 git fetch 写入只读候选工作区或共享 Git refs。
• 核验实际 checkout/tree 与正式候选 SHA；未经认领的 PR、错误 SHA/仓库、已移动 head 或旧工作树不作为当前候选。
• Use role-bound GitHub App identities for SDK development, reviews and delivery reconciliation #2365 负责正式候选/PR 认领回写；本条在其成功前给出明确 blocked-on-binding，不用联网成功、MERGEABLE 或模型输出绕过。
• PR 为 fork/跨仓来源时遵守现有明确授权范围；不得借本条自动扩展跨仓执行或把写凭据复制给外部仓库。

3. 可信 PR、CI 与 build 证据

• PR 元数据、head/base SHA、draft/state/hold、真实 Review 与检查状态从实际 GitHub 查询产生，记录来源、经核验的 App/installation、观测时间、对象/运行 ID及对应完整 SHA。
• 配置需要的门禁应读取足够页数/端点，并处理 checks/statuses/workflow run 等实际使用的检查来源。超出预算或缺页是 unknown/incomplete，不能因第一页没有失败就判全部通过。
• 校验所需检查名称/来源/适用 head，保留 pending、failure、cancelled、missing、unknown 与 success 的差别；按当前项目的轻量或实际配置判断，不强制所有项目继承 FlyBot 重门禁。
• 区分 Reviewer 自己执行的命令、Tester/宿主真实 build/test、GitHub CI、Review 判断及最终合入，不虚构“亲自执行”，不把无 CI 当有 CI 通过。
• 构建/测试需要写目录、依赖或网络时，复用 Validate dependency readiness and distinguish environment blockers from code test failures #2334 的准备和独立验证能力；只读源码保护继续保留。环境不具备时记录 Not run/具体原因，不能视为代码测试失败或默认需要用户操作。
• 为 Reviewer 提供可读取的受权、限长、可分页日志/产物入口与来源/哈希；不能只给 SDK 无法访问的宿主绝对路径，或让它相信一段不可核验的摘要。
• input.publish 可携带线索/对象引用，触发实际查询与对账；不能把其中的“build passed”等自由文本升级成正式 evidence。
• 外部评论、日志、diff 与 PR 正文是内容数据，不是授权指令；不能据此切换身份、目标、检查策略或声称批准。

4. 结果记录、变化与恢复

• 复用现有 evidence、操作回执与 Effects，不另建 Review 状态库/调度器。角色结果与实际 GitHub Review、正式 candidate、App 身份、原 Session/claim/generation 关联。
• 审核前后重验 head/candidate/base 和当前权限；源码发生变化时保留旧结论，但不得批准新 SHA。
• 查询/下载失败、CI 待完成、绑定缺失、日志不可读、环境未就绪等错误，返回具体缺口、已经取得的证据、未执行项目及合法恢复方式。
• 交由 Chief 自主选择重查、来源认领、测试请求、返工或必要咨询；框架不固定转人工、默认派工或把有限源码结论伪装成完整批准。
• 重复消息、请求超时、Token 刷新、宿主重启、旧 SDK 结果迟到及实际 Review 写入结果未知时先对账，不能重复提交审核或把旧 SHA 结果写入当前 Attempt。
• Automatically enter the host merge flow after Reviewer approval of the current candidate #2331 负责实际 merge/queue 门禁与合入结果，Reviewer 结论本身不等于已经合入或 Task 完成。

验收与测试

• 当前 deny-all 网络下的 SDK Reviewer 访问缺口有隔离红/绿复现；修复后本地与 Docker 使用获准 App 身份实际读取私有测试 PR/Review/检查，无需运维 input.publish 元数据。
• 主路径覆盖 SDK Dev 创建的 PR，以及已通过 Use role-bound GitHub App identities for SDK development, reviews and delivery reconciliation #2365 正式认领的外开 PR；候选源码、PR head、Review 与测试/CI 证据绑定同一完整 SHA。
• Token 已配置但网络不通、网络通但身份/权限不足、绑定缺失、对象不可见、日志不可读分别返回正确原因，不直接 awaiting-owner。
• Reviewer 只读候选不被 fetch/build 修改；需要的对象传输和可写 scratch/验证路径实际可用。
• 伪造 input.publish 成功说明、MERGEABLE、第一页检查不完整、错误检查来源/旧 SHA、无 CI 与 CI pending/failure 等不能产生伪通过。
• head/base/权限变化、重复回调、重启、超时及未知 Review 写入结果得到幂等对账，旧结论不迁移到新候选。
• 原生/SDK 共用证据语义；实际 SDK、GitHub App 读写、真实构建和确定性 fixture 分别报告，不能互相替代验收。
• 更新长期记忆、Harness/网络/资源/GitHub/Review/交付架构、角色提示、资源配置与部署排障说明、接口/OpenAPI 和回归用例。

范围边界

本次只授权落 Issue，不修改主会话代码、现场 PR/任务、资源 allowlist、凭据或服务部署。真实 SDK/GitHub 验收使用另行明确授权的测试资源/App 安装；不开放任意网络、不取消只读候选保护、不修改仓库门禁、不借个人身份、不合入现场 PR或触发发布。