feat(research): execute public GitHub evidence with auditable downstream readback

[jackie-cqz]

Goal and delivered boundary

Refs #5205 (S6/S8). Deliver the selected public GitHub provider/CLI stage: anonymous retrieval from full-SHA-pinned UTF-8 files, source provenance bound to the exact plan, separate parent admission, actual downstream source-ledger use and readback. The typed external-evidence contract owns admission; the existing deepresearch ledger owns downstream lineage.

• Opt-in bundled method:public-github uses bounded anonymous GETs and fresh public-visibility checks, without credentials, redirects or persisted raw source bodies. Findings cover retrieval and literal matches; semantic completeness remains unverified.
• Optional source refs/search terms enter exact request/plan identity while legacy request digests remain compatible. Mutated plan/admission semantics fail before execution or writeback.
• readback independently reports receipt, parent decision, matching ledger lineage and retirement. Explicit execution projects only admitted sources into an existing matching-question research run; partial projection stays retained, retries are idempotent, and original-source fallback remains available.
• The existing conversation answer/report and Lark Markdown transports display shared readback. Case-sensitive pinned file paths are preserved. No new configuration switch, registry, evidence store or scheduler is added.

This is a partial provider stage: the packaged frontend renders admitted evidence. Starting retrieval and admission through the existing App research interaction remains open under #5205; this PR does not complete the whole frontend journey, authenticated providers or overall S6/S8 acceptance. The RFC checkpoint records that boundary.

Current qualification

Head: bff8e4cf9e60982b80369fd499d9553dd29a9366. Merge base: 5e889bdcba9cea101a8775340a12629eb5a2474a, PR base main. All seven PR commits carry DCO sign-off.

• Linux Python 3.11 source-installed provider, deepresearch, architecture and shared CI regressions: 95 passed. Focused typed external-evidence suite: 17 passed.
• Exact CI mypy 1.20.2 passed all 19 configured sources. CI Ruff, TypeScript control-plane typecheck and full semantic inventory smoke passed.
• Exact Linux CLI output-budget smoke passed on both base and head; no budget changed.
• Current-head real anonymous provider smoke fetched the public LoopX README pinned to the base SHA: receipt before admission, retained before projection, explicit parent admission, matching actual ledger readback and idempotent projection all passed; raw content was not persisted.
• Packaged Chat build and desktop/mobile evidence-readback browser scenario passed before the final rebase, including reload. Its frontend files are unchanged by that final base update. Existing Lark presentation/splitting coverage passed earlier; live Lark delivery and authenticated connectors were not exercised.
• Shared real-wheel install/uninstall qualification on the rebased peer branch passed the current release workflow validator for all eight skills; the shipped metadata contract is identical here.

Shared fixture repairs preserve the actual queue claim, read-only Todo delivery contract and isolated runtime roots. Rebase includes upstream #5463/#5479 and drops their duplicate doctor/skill patches. Future-facing pass retains the existing typed admission and source ledger owners; no additional abstraction is needed for this repair.

Hosted CI and maintainer review/merge remain required. The broader issue remains open for the explicitly remaining boundaries above.

[mergify]

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @jackie-cqz.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[huangruiteng]

Reviewer: model_agent | GPT-5 | OpenAI

动机

结论：APPROVE 这份明确有界的 public-GitHub provider/CLI 阶段，head b635a65；没有发现阻塞问题。#5205 需要从真实取证走到父 Agent 决定和下游实际使用，原有 receipt 入口只能证明 caller-presented 记录。新增路径把匿名、固定完整 SHA 的公开文件读取接到现有生命周期，不能把它说成整个研究能力或 App 发起旅程已完成。

改动思路

公开 GitHub HTTP 属于 bundled provider；精确 plan/receipt/admission/retirement 仍由现有 TypeScript owner 决定。Python CLI 在访问网络前核验 canonical plan，把 provider 结果交回同一 TS owner；显式父决定后，readback 才能把已采纳来源投到既有 deepresearch source/claim ledger，再独立核对真实 lineage 和 claim。既没有新 evidence 数据库，也没有自动采纳、connector promotion、调度或配额副作用。保留 Python 的部分是 HTTP 与已有文件账本传输，不是第二套通用决策源。

具体改动

• 「execute_public_github」（loopx/extensions/public_github_research.py:76）：只处理显式选择的 method 和一至八个 full-SHA 文件；每次重新检查仓库 public，拒绝重定向/外部 origin/非法路径，字节有上限，只返回 digest、取证时间和 literal-match 元数据。公开读取不是授权证明，literal match 也不是语义研究结论。
• 「handle_external_evidence_command」（loopx/capabilities/external_research/cli.py:199）：新增 opt-in plan readiness、execute 和 readback；--public-github 会做匿名 readiness GET，真正内容执行必须 --execute。source/search 可选字段纳入 TS request identity；省略时旧 request digest 不改变。caller-presented receipt 与真实执行仍保持区别。
• 「readback」（loopx/capabilities/external_research/projection.py:33）：先通过 TS 重建精确 parent admission；默认只读，execute 必须有 admission 和既有 matching-question project。账本局部失败保持 retained，覆盖不能由成功消息或 caller 给的 URL 冒充。Markdown 明确显示 pending/admit、covered、retirement 与 completeness unverified。
• 「add_source」（loopx/capabilities/deep_research/runtime.py:235）：在原文件锁内比较 lineage 和 claims，精确重试读回已有 id；GitHub pinned path 区分大小写，普通来源仍保留旧 normalization。当前 run 的 question 不匹配、来源冲突、预算耗尽均不伪造 coverage。

完整差异为 19 文件、+859/-37，已阅读 provider、TS optional request 字段、CLI/catalog、ledger/projection、双语 RFC/操作说明、public CLI smoke、现有 answer/Lark 展示测试和五个共享 UTF-8/read-only/Windows/安装测试修正。没有修改 App 生产代码；新增 browser fixture 把实际 typed/ledger Markdown 注入已有 answer API，不能证明用户从 App 发起 provider/admission。未来方向检查：当前继续复用既有 typed owner 和 ledger 足够，不需加一层 provider registry 或迁移框架。

以改动前已接受 RFC 为独立依据：spec_ref = docs/architecture/rfcs/external-evidence-research-capability-v0.md；spec_revision = 4fc30f1。规范没有单独条款编号，criterion_id 使用 Acceptance 的原文条款开头：

criterion_id	判定与证据
inventory-only connectors cannot be selected	TS discovery/selection 原有负例通过；没有把 catalog 或 installed 当 ready。
discovery distinguishes empty, inventory-only, and ready inventories	现有 CLI/TS 矩阵通过；inventory 不声称执行或覆盖。
method and connector providers use one protocol and receipt contract	provider 经同一 external_evidence.receipt 校验；没有另造 admission。
an observed provider receipt is bound to the exact plan	真实匿名 README 执行和 receipt 回读通过；没有自动采纳。
mutation of the request objective, decision, constraints, provider readiness	TS 负例及实际 CLI 改 objective 后退出 1、完整 request_id 诊断通过。
stale request/provider identity, file provenance, and unsupported evidence	既有 TS/CLI 负例通过；provider 的坏 URI、路径与可见性失败不产生可用来源。
admitted source refs are a subset of receipt sources	TS admission 负例通过；实际 CLI 缺失 admission 拒写，账本仍空。
retirement rejects mutated disposition, source, or downstream projection	实际 CLI 修改 parent reason 后拒绝，未增写来源；typed 变异矩阵通过。
retirement waits for downstream coverage of every admitted source	真实 CLI retained→ledger→retire_ready；错误 question、不匹配 lineage、局部预算失败保留 retained。
CLI and effect-runtime TypeScript tests pass from the source checkout	55 项 Python 与 17 项 TS 通过，并执行下面的独立真实入口验证。

对主干的风险

独立验证：完整 source CLI 对匿名公开 LoopX README（固定 4fc30f1）执行 plan→真实 provider→receipt→显式合成父决定→既有 ledger→retire_ready→同身份重试，通过；未保存原始文件内容。另用同一合成 fixture 在不可变 base 与该 head 执行 legacy plan/receipt/admit/retire、普通来源去重和非法 plan 的完整退出/诊断，归一化后逐字段一致（只去掉 ledger wall-clock 时间）。相同输入 fingerprint 为 c90ea94aee0938c718af868d802c5f6974444aec4bfbefab9d621b698449a40b，两个观察 fingerprint 都为 594c67372271bb5b4155350047979b4734721bc563ee114a73daadc8534ea01a。

实际 CLI 负路证明：无 parent admission 不写；被篡改 admission 拒绝；无关 question 仍 retained；添加无关来源不改变覆盖；新 project 在明确投影前不算 covered，合法重试恢复到 retire_ready。另故意让投影边界丢失 lineage，再走真实 ledger/readback，完整覆盖 oracle 失败、结果仍 retained；恢复正确参数的新 project 通过，不会把存在同 URL 当有效使用。Ruff、编译、diff check、语义 advisory 和当前 packaged bundle 构建通过。55/17 是本次运行结果，不继承作者的 Windows/wheel/浏览器结论；评审 harness 的错误路径和遗漏 title 参数已纠正，不归罪于 PR。

保留边界：本轮 ego-browser 原空间无法恢复，因此 packaged answer 的浏览器复验未完成，没有声称桌面/移动 reload 已通过；App 生产代码未变，此次批准限真实 provider/CLI 阶段。现有 Lark card/长文拆分测试通过，但没有 live Lark 发送、认证 connector、付费模型、安装推广或研究完整性验证。未查询或等待 CI；没有合并。原始来源 fallback 明示保留，失败或部分结果不驱动自动采纳。

我的整体评价

这是可独立验证和回滚的有用增量，不是仅加 receipt serializer。真实匿名 provider、TS 身份、父决定、文件账本与重试已经连成可操作链路；复用相邻 owner 优于再建通用存储。重复同一 pinned source 的不同 admission 仍可能遇到既有 source 冲突，应遵循现有“复用 claims/明确另开 run”的恢复语义，不扩大默认权利。剩余 App 研究交互发起/采纳、authenticated connector 和最终 companion qualification 继续归 #5205；不要关闭整体 S6/S8 或把 catalog/命令说明算成完整 frontend 交付。APPROVE 不是 merge authority，也不表示已安装生效。

English verdict: APPROVE - b635a65: no blocking finding in the bounded public-GitHub provider/CLI stage; anonymous real-provider/ledger retry and immutable base/head parity passed, 55 Python and 17 TypeScript tests passed. Full App initiation and this turn's browser requalification remain unproven; no merge.

[mergify]

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @jackie-cqz.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[jackie-cqz]

Updated the branch by rebasing onto 5e889bdcba9cea101a8775340a12629eb5a2474a; current head is bff8e4cf9e60982b80369fd499d9553dd29a9366. Duplicate doctor/skill patches now owned by upstream were dropped, and shared queue/runtime/Todo test fixtures were repaired without weakening their negative assertions.

Current validation: 95 Python regressions and 17 typed external-evidence tests passed; exact CI mypy/Ruff, TypeScript typecheck, semantic smoke and paired base/head CLI budget passed. The real anonymous provider smoke on this head passed retrieval, separate admission, actual deepresearch ledger readback and idempotent projection for the full-SHA-pinned public README, without raw-content persistence. Shared actual-wheel install/uninstall validation also passed the current release validator.

The PR remains the approved bounded provider/CLI stage: packaged App readback is present, while App retrieval/admission initiation and overall #5205/S6/S8 completion remain open. The body replaces stale qualification details with current head-specific evidence. Hosted checks are rerunning.

[huangruiteng]

Reviewer: model_agent | GPT-5 | OpenAI

动机

没有发现本次有界 provider/CLI 阶段的阻塞问题。原来外部证据可以描述计划和回执，却没有随产品交付的公开 GitHub 执行器，也不能从实际 source/claim ledger 独立证明已采用证据。这是 #5205 的 S6/S8 justified increment，不是整个研究交互已完成。评审重新读取当前全部 20 文件及基线；旧 head 的已撤销批准没有替代本次证据。

依据修改前的 docs/architecture/rfcs/external-evidence-research-capability-v0.md，固定版本 5e889bd，原 Acceptance 条款逐项映射如下（标识沿用原条款文字）：

• inventory-only connectors cannot be selected — implemented；inventory-only connectors cannot be selected。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• discovery distinguishes empty, inventory-only, and ready inventories — implemented；discovery distinguishes empty, inventory-only, and ready inventories without claiming execution or evidence coverage。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• method and connector providers use one protocol and receipt contract — implemented；method and connector providers use one protocol and receipt contract。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• an observed provider receipt is bound to the exact plan — implemented；an observed provider receipt is bound to the exact plan without implying authenticated execution, evidence coverage, admission, or promotion。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• mutation of the request objective, decision, constraints, provider readiness — implemented；mutation of the request objective, decision, constraints, provider readiness, or execution envelope fails canonical plan_id verification。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• stale request/provider identity, file provenance, and unsupported evidence — implemented；stale request/provider identity, file provenance, and unsupported evidence basis fail closed。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• admitted source refs are a subset of receipt sources — implemented；admitted source refs are a subset of receipt sources。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• retirement rejects mutated disposition, source, or downstream projection — implemented；retirement rejects mutated disposition, source, or downstream projection fields whose complete admission identity no longer matches。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• retirement waits for downstream coverage of every admitted source — implemented；retirement waits for downstream coverage of every admitted source。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。
• CLI and effect-runtime TypeScript tests pass from the source checkout — implemented；CLI and effect-runtime TypeScript tests pass from the source checkout。由现有 TS 生命周期及本轮 typed/实际 CLI-ledger 验证覆盖。

完整 App 内发起检索、作出 admission 及授权 connector 的资格验证仍 deferred 到已有 #5205 的 capability/App owner。本阶段独立可逆，匿名 provider 和 CLI 到持久 ledger 的链路现在实际可用；不新增设置、不借用安装或 discovery 来授权执行。

改动思路

仍由 external_evidence.ts 决定请求身份、provider 选择、parent admission 与 retirement；Python 只承担 HTTP transport、CLI 编排和已有 deepresearch 领域 ledger 的适配，未建立第二个通用决策源。用户选完整 SHA 来源，明确请求网络读取，得到 observed receipt，再独立提供 parent 意图，最后对匹配问题的研究 run 显式投影。每一步分别提供范围、读取权限、采用意图和落地目标，不是重复确认同一事实。成功回执不自动意味着 admission，更不意味着 downstream coverage。

相比另建 evidence store 或手写 ready 标志，最小有用路径是在已有锁保护的 source/claim 上保留四个身份 digest，再每次读取实际来源、claim 和问题，派生覆盖。CLI/typed owner、deepresearch ledger、现有 answer/Lark Markdown 消费者及未变的 frontend 兄弟路径均作过基线比较。来源拒绝、预算不足或错误问题保留 retained，用户可纠正目标后继续；不会丢弃失败或循环宣布完成。

具体改动

20 文件 +861/-35 包括 131 行 bundled GitHub provider、111 行 readback adapter、已有 CLI/deepresearch/TS contract 的小扩展、catalog availability、双语阶段与操作文档，以及聚焦 provider、ledger 和现有原生 fixture 的验证。source_refs/search_terms 缺省时不进入旧身份计算，显式来源才进入 exact plan；带 lineage 的完整 SHA 路径保持大小写，普通 source 的历史归一化和重复错误仍保留。共享 fixture 修复遵循真实 queue claim、read-only continuation 和独立 runtime root；skill metadata 按已选择的 shipped catalog 验证，不把固定数量当能力契约。

关键代码讲解

• execute_public_github:76：仅接受已选择的 method 和验证后的计划。公开可见性先查，来源必须固定完整 SHA；最多八个、UTF-8 且有字节上限，禁重定向，不读取凭据。成功只产生 provenance/literal-match 摘要，partial/unavailable 不能变成证据完整性。
• handle_external_evidence_command:199：沿用实际 CLI dispatcher；执行前调用 TS 验计划，execute/readback 需要对应显式请求。无执行授权的生命周期与旧输出不发生 HTTP 或 ledger 写入；无效输入明确拒绝。
• readback:33：重新验证完整 admission，仅显式 project/execute 才 add_source；从当前实际 ledger 的同问题、同来源、四 digest 和 claim 读取覆盖。仅有相同 URL 或 receipt 不会 ready；缺失、冲突与部分预算仍 retained，修正匹配 run 后可恢复。
• add_source:235：沿用原锁、source/claim ID、预算及 save owner；exact lineage 重试复用同一记录，而普通调用保持原语义。独立 mutation 丢弃 lineage 后实际写入虽成功，ready oracle 必须失败；恢复生产 adapter 后同一真实 CLI 路径通过。

对主干的风险

本轮从精确 source checkout 执行：131 项 Python（provider、CLI、deepresearch、native continuation、Codex queue、runtime configuration、skill metadata/parity），17 项 TS；配置要求的 Ruff、19-source mypy、control-plane typecheck、full semantic vocabulary smoke、diff check 全通过。真实匿名 HTTPS smoke 读取固定 5e889bd 的公开 README，逐步验证 receipt-before-admission、projection-before-ready、实际 source ledger 与 idempotent retry；未持久化原文。独立实际 CLI+TS+file ledger oracle 验证 forged admission、错误问题、未授权写、新研究 run、无关来源和 dropped-lineage 反例。fixture fingerprint c90ea94aee0938c718af868d802c5f6974444aec4bfbefab9d621b698449a40b；缺省分支基线/head 完整归一化观察均为 594c67372271bb5b4155350047979b4734721bc563ee114a73daadc8534ea01a，只剔除已声明非确定时间，不抹掉诊断、身份、状态或副作用。

最强风险是“URL 出现就算已采用”或“发现 method 就自动执行”；实际 lineage/readback 与显式 flags 拒绝这些路径。默认关闭比较涵盖共享 TS/CLI/ledger；catalog/help 只是 availability，不是执行义务。GitHub 暂不可达、二进制或部分结果不能被误称完整证据。literal matches 的语义完整性仍 unverified。App 生产代码未改变；浏览器本轮不可用，未恢复或替换浏览器，新增 synthetic renderer fixture 和作者前次浏览器声明不作为本轮完整 App 交互证明。现有 Lark display 覆盖不等于 live delivery。

语义与 CI 对齐

扩展既有 exact-request 词汇的可选 intent 和既有 source format 的可选 producer lineage，不新建 actor lifecycle、共享 evidence authority 或 scheduler 义务。typed plan/admission 是执行规则，文档 guidance 没有把强制 flag 说成建议。开发 advisory 的空结果不证明语义等价；本轮 full canonical semantic smoke 和现有 CI 配置对应的本地检查才是相应覆盖。未查询、轮询或等待 GitHub CI，也未放宽任何预算。

我的整体评价

APPROVE，仅批准上述有界 provider/CLI stage。long_horizon improved：来源身份、实际采用与重试都可回读，错误保留并能恢复，避免重复写和虚假退休。user_experience accepted_tradeoff：本阶段 CLI 的最短合法链路有用且授权明确，完整 App 发起/采用尚在原 #5205，不宣称已安装修复。代码量主要投入真实边界验证；未来重构 pass 已比较已有 typed lifecycle、领域 ledger 与 provider seam，当前复用合理，未发现需要追加框架或语言重写的相关小重构。重新核验旧评审与当前 head，批准后只处理确已过期且有权限的 blocker；不凭本批准覆盖未解决问题，不执行合并。

English verdict: APPROVE - HEAD bff8e4c. The bounded anonymous public-provider/CLI stage is independently validated. Full App initiation/admission, authenticated providers and live messaging remain explicitly outside this approval; no merge or installed-state claim.

[mergify]

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @jackie-cqz.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork