test: add PI release proof harness

docs/pi-runtime-release-runbook.md

@@ -0,0 +1,66 @@
+# Pi Runtime 发布与回滚
+
+本文定义 Makelore Code 当前 Pi Runtime 正式包的发布门槛、兼容边界和整版本回滚方式。它是发布操作契约，不是历史证据归档；每次执行产生的 JSON、日志、安装包和性能报告都保存在忽略的 `release/` 目录或外部发布系统中。
+
+## 发布边界
+
+- 正式包固定使用仓库锁定的 Pi 版本和生产依赖闭包。Electron Main 从安装目录中的 `resources/pi-runtime` 解析运行时、扩展、Manifest 与编码 Skills；缺失、版本漂移、开发路径泄漏或 OpenCode 命名资源残留均阻断发布。
+- Renderer 只使用 Main-owned Host API 和产品 Conversation 契约，不读取 Pi wire 类型，也不直接启动 worker、访问本地运行时地址或接触 Provider 凭证。
+- 产品保留既有 `niancode` 应用 id、协议、数据目录和项目配置兼容标识；这不代表旧 OpenCode 运行时、路由或资源仍被携带。
+- 正式产品界面不提供 share/unshare、revert/unrevert、todos 或全局运行时控制。项目分支只创建新的 Conversation 历史，不表示文件回滚。
+
+## Conversation 兼容性
+
+升级前已有的 OpenCode Conversation 数据继续保留，项目首次进入 Pi 会显示一次迁移说明，但 Pi 不导入、续写或改写这些旧 Conversation。升级后新建的 Pi Conversation 使用新的本地契约；旧版本不能读取或续写它们。
+
+因此，旧 Conversation 的“保留”是可回滚的数据边界，不是跨运行时续写兼容。不得通过复制 Session、混用资源目录或在同一安装中切换旧/新 runtime 来绕过该边界。
+
+## 必须验证的正式产物
+
+发布候选必须分别提供以下最终产品证据：
+
+| 目标 | 最终产物 | 必须结果 |
+| --- | --- | --- |
+| Windows x64 | 安装器与 `win-unpacked` | 产物验证、Pi smoke、性能报告均 Pass |
+| Linux x64 | 发布包与 `linux-unpacked` | 产物验证、Pi smoke、性能报告均 Pass |
+| macOS x64 | 对应架构应用包 | 独立产物验证与 Pi smoke Pass |
+| macOS arm64 | 对应架构应用包 | 独立产物验证与 Pi smoke Pass |
+
+缺少任一目标的独立证据时，结论只能是 `Blocked`，不能用其他平台、staging 目录、源码测试或用户豁免替代跨平台发布就绪结论。
+
+每个平台在完成打包后，从该平台的最终应用可执行文件运行：
+
+```bash
+pnpm run verify:artifact:pi -- --app-exe <final-product-executable> --samples 5 --report <artifact-report.json>
+pnpm run smoke:pi:real -- --app-exe <final-product-executable> --samples 5 --report <smoke-report.json>
+pnpm run perf:pi:release -- --app-exe <final-product-executable> --samples 5 --report <performance-report.json>
+```
+
+产物验证必须确认版本与 Node engine、生产依赖闭包、扩展、Manifest、编码 Skills、`resolve/get_state`、无 OpenCode 资源以及无构建工作区绝对路径。Smoke 必须从最终产品可执行文件启动最终 `resources/pi-runtime`，覆盖 session、prompt、tool、abort、settle、reopen、双 worker 重叠与隔离、子 Agent 和 shutdown。性能报告必须记录 p50/p95/max/样本数组、RSS、Main→Renderer IPC/提交延迟和 Git commit，并覆盖 Spec 17.3 的十个场景。
+
+## Provider 验证的准确含义
+
+`smoke:pi:real` 中的 `real` 指真实最终 Pi 进程与最终产品资源，不指真实外部 Provider。受控 Provider-shaped 回环服务只证明 Makelore/Pi 的协议与隔离路径按预期运行。
+
+如果发布决定明确豁免真实 Provider 验证，报告必须保持 `realTurnVerified=false`，并把 QG-004/QG-005 标为 `Explicitly Waived / Accepted Risk`，不得写成 Pass。被接受的剩余风险包括真实 Provider 的协议差异、限流与并发策略、凭证隔离，以及多模态输入的供应商特定行为；报告和日志不得包含真实凭证。
+
+## 发布判定
+
+只有下列条件同时成立才能发布：
+
+1. 固定 pnpm 版本的 frozen install、typecheck、lint、unit、production build 和完整 Electron E2E 通过。
+2. 四个目标的最终产品产物验证与 Pi smoke 均通过，且报告对应同一 Git commit。
+3. Spec 17.3 场景与性能预算通过，没有源码目录、staging 目录或开发 fallback 代替最终产物证据。
+4. 真实 Provider 若未验证，已由发布负责人显式接受上述风险，并保持非 Pass 状态。
+
+## 整版本回滚
+
+Pi 与旧运行时之间只支持完整应用版本回滚，不支持运行时组件级回滚或混装：
+
+1. 停止发布和自动更新，完整备份目标用户数据目录及项目中的 `.niancode` 数据。
+2. 退出 Makelore，确认没有 Pi worker 或安装器进程仍在运行。
+3. 安装上一完整、已验证的应用版本；不得把旧 runtime 覆盖到新版本 `resources`，也不得保留新旧文件拼接后的安装目录。
+4. 旧版本只继续使用其原本可读的旧 Conversation。升级后新建的 Pi Conversation 保留在磁盘中，但对旧版本不兼容，不能读取或续写。
+5. 需要重新升级时，安装完整 Pi 版本并重新执行该版本的项目迁移与一次性说明流程；不要在不同版本间复制 Session 文件。
+
+回滚完成后，应验证应用标识与用户数据目录未改变、旧 Conversation 仍可按旧版本能力读取、Pi Conversation 字节未被旧版本改写。任何需要手工编辑 Conversation 文件才能恢复的情况都应停止操作并保留备份。