# ML-CODE-PI-001 实施票据与依赖图

## 0. 文档信息

| 字段 | 值 |
| --- | --- |
| 关联 Spec | `ML-CODE-PI-001` |
| 状态 | 实施中；`PI-000` Done with explicit waivers |
| Task | `20260822-pi-runtime-spec-b6e2c9a4` |
| `PI-000` 实施基线 | `2bc423ebc58589307442ebdaf1c81d83ec9dc2d5`（`feat: qualify Pi runtime cutover foundation`） |
| 目标 | 把完整硬切换拆成可验证、无循环依赖的执行图 |
| 当前 Ready Frontier | `PI-010`, `PI-020`, `PI-030`（`PI-000` 已 Done with explicit waivers） |
| Phase-0 macOS | **Explicitly Waived / Deferred by user on 2026-08-22**；不是 Pass，实际验收移至 `PI-150` |
| 真实 Provider | `QG-004`/`QG-005` **Explicitly Waived / Accepted Risk by user on 2026-08-22**；不是 Pass，也不再阻断 release |

本文中的“票据”是仓库内实施单元，不代表已经创建 GitHub Issue、分支、PR 或子智能体。后续执行者可以把票据同步到外部 issue tracker，但票据 ID、依赖和验收语义必须保持。

## 0.1 当前规划状态（2026-08-22）

| 字段 | 当前判断 |
| --- | --- |
| `PI-000` 实施任务 | `20260822-pi-runtime-qualification-c52e8a14`；commit `2bc423e`；`ready_for_integration` |
| `PI-000` 状态 | Done with explicit waivers；不是全部 QG Pass |
| 规划 frontier | `PI-010`, `PI-020`, `PI-030`；其余票据继续按 31 条依赖边锁定 |
| `PI-010` 交接 | `20260822-pi-conversation-contracts-a61d9c42`；基线 `2bc423e`；当前 `planning` |
| 资格证据 | `.project-docs/50-evidence/topics/20260822-pi-runtime-qualification-c52e8a14__pi-runtime-qualification.md` |

已确认事实：

- `PI-000` 已作为 commit
  `2bc423ebc58589307442ebdaf1c81d83ec9dc2d5` 提交；实施工作树干净，任务登记为
  `ready_for_integration`。`PI-010` 已在该 commit 上建立独立工作树并进入
  `planning`；这不改变依赖已满足的 Ready Frontier 定义。
- 精确候选 pin 为 `@earendil-works/pi-coding-agent@0.84.2`；上游 tag
  `v0.84.2`、npm `gitHead` 与 commit 均为
  `914cf1472e715297caa30db4b9535d534a9eb718`。
- Windows x64 的 workspace、临时 production closure，以及独立受控 Electron
  Builder `dir`/`app.asar` probe 均可通过 `ELECTRON_RUN_AS_NODE=1` 启动 Pi
  RPC。受控 artifact 使用 `MakelorePiProbe.exe` 和
  `resources/app.asar/dist/cli.js`，刻意不继承 Makelore 正式
  `electron-builder.yml` 的 OpenCode/Python/UV/signing/install hooks，也没有
  改动最终产品打包 wiring。
- 受控 artifact 可定位 Pi 0.84.2、CLI、130 个 Windows 适用 production
  packages、9 个按平台跳过项和 6 个 runtime WASM/native assets；`.node`
  位于 `app.asar.unpacked`。Electron Builder 把同版本
  `@types/retry@0.12.0` 从 `p-retry` nested layout 扁平化到 root
  `node_modules`，属于可解析布局变化，不是依赖丢失。
- 受控 packaged artifact 的 5 cold / 5 warm 样本分别为：cold
  p50/p95/max 668/682/682 ms，warm 660/663/663 ms；10 个 RSS 样本
  138404/141320/141320 KiB；exit 16/18/18 ms。session/reopen、
  deterministic failure、local shell overlap、单侧 abort isolation、stdin
  close 均通过，结束后没有 artifact 或 Pi RPC 残留进程。
- packaged runtime 上的 `127.0.0.1` HTTP/SSE 合同 probe 已覆盖
  `openai-completions`、`openai-responses`、`anthropic-messages`、`openrouter`。
  每种协议恰好产生 4 个 POST，验证 base URL/path、环境凭据 header、custom
  header、model、PNG image、双 worker 成功 settled、turn 重叠、单侧 abort
  与另一侧成功以及 stdin-close；最终收紧重跑的重叠时间依次为
  304/309/290/297 ms。
- Anthropic 配置使用 Provider root，由 SDK 追加 `/v1/messages`；OpenAI 风格
  base URL 以 `/v1` 结尾，再追加 `chat/completions` 或 `responses`。该差异应
  进入后续 Provider catalog fixture，而不能对四种协议统一拼接路径。
- 最终 focused suite 为 9 tests；scoped ESLint、typecheck、`build:vite`、
  `git diff --check` 和 project-doc drift gate 已通过。
- Linux x64 在 WSL2 Ubuntu 24.04、kernel
  `6.6.87.2-microsoft-standard-WSL2` 中取得 workspace、staged production
  closure 与 controlled Electron Builder `dir/app.asar` 三层证据。隔离快照以
  Node 22.22.2 和仓库 pin `pnpm@10.33.4` frozen install，运行 seam 为
  Electron 43.4.0 与 embedded Node 24.18.1。
- Linux workspace 5 cold / 5 warm：cold p50/p95/max 426/853/853 ms，warm
  432/437/437 ms，RSS p95 170388 KiB，exit p95 8 ms。staged closure：cold
  426/428/428 ms，warm 423/440/440 ms，RSS p95 175956 KiB，exit p95 8 ms。
- Linux controlled `dir/app.asar`：cold 526/545/545 ms，warm 545/569/569
  ms，RSS p95 181928 KiB，exit p95 7 ms；131 个 Linux 适用 package、8 个
  platform skip、6 个 runtime asset 和 unpacked native assets 均无缺失，只有
  与 Windows 相同的同版本 `@types/retry@0.12.0` flattening。
- Linux packaged 四协议 loopback 每种恰好 4 个 POST，路径、鉴权头、自定义
  header、model、PNG image、双 worker overlap、单侧 abort isolation 与清理
  均通过；overlap 依次为 292/290/277/288 ms，结束后无 artifact/Pi RPC
  残留进程。Linux 报告代码也已移除运行时仍硬编码“Linux missing”的字段，
  改为 cross-platform aggregate requirement；7 tests、scoped ESLint、
  typecheck 和 1-sample integration probe 通过。
- macOS 实跑前发现并修复一个真实 packaged-closure path defect：旧 inspector
  在 artifact 内用 `dirname(process.execPath)/resources` 推导资源目录；macOS
  executable 位于 `<app>/Contents/MacOS/MakelorePiProbe`，旧逻辑会错误读取
  `Contents/MacOS/resources/app.asar`，实际路径是
  `Contents/Resources/app.asar`。
- 修复后由外层 platform-aware `packagedResourcesDirectory()` 只计算一次资源
  目录，并通过 `PI_PROBE_RESOURCES_DIRECTORY` 传入 artifact process；closure
  inspector 不再二次推导。focused test 已覆盖 darwin executable →
  `Contents/Resources`。
- 修复后的 Windows controlled packaged actual regression 以 1 cold / 1 warm
  样本通过，ready 为 650/641 ms；130 个适用 package、6 个 runtime asset 与
  unpacked native asset 均无缺失，证明显式资源目录传递没有破坏 Windows。
  这只验证修法和 Windows 回归，不是 macOS 运行证据。

未验证但由用户于 2026-08-22 明确接受、且不再阻断 `PI-000` 或 release 的风险：

- 四协议 loopback 只证明 Pi request serialization、SSE parsing、图片/header/
  model/credential plumbing、worker 重叠与 abort 隔离。它没有发起外部请求或
  产生费用，也不证明任何真实 Provider Account、认证、proxy、rate-limit 或
  provider-specific response variance；四协议真实 endpoint/account/credential/
  successful settled/concurrency/abort/reopen/image-where-supported 样本仍缺失。
- 用户明确接受真实认证/endpoint/proxy/rate-limit/provider-specific response
  variation，base URL/header/environment credential/model/image 的真实协议兼容，
  真实 provider 并发或串行/限流，以及跨 worker abort/event/session/model/
  credential 隔离风险。`QG-004`、`QG-005` 因此标记为 **Explicitly Waived /
  Accepted Risk**，不是 Pass；所有资格/发布报告继续保留
  `realTurnVerified: false`。

用户明确豁免并延期的 Phase-0 项（不是 Pass，也不再阻断 `PI-000`）：

- 用户于 2026-08-22 决定跳过 `PI-000` 的 macOS 实跑。macOS x64 与 macOS
  arm64 标记为 **Explicitly Waived / Deferred by user**；workspace、staged
  production closure、controlled packaged seam、packaged loopback、资源和
  metrics 全部移至 `PI-150`。
- darwin 资源路径 preflight defect 已修并有静态测试，但两个架构都尚未实际
  运行，所以不得标记 macOS Pass。延后可能使 packaging/native/resource/
  performance defect 到 release stage 才暴露并造成返工；这是用户接受的风险，
  不是已消除风险。

范围限定和后续约束：

- 当前 Linux 证据来自真实 Ubuntu 24.04 x64 用户空间、Linux executable/native
  selection、asar layout 和 process seam，但 kernel 为 WSL2 且 artifact 是
  controlled Builder `dir`。正式 Spec 的 `QG-002` 只明确要求 Linux packaged
  app，没有额外要求 non-WSL kernel、native compositor、AppImage 或 deb，
  因此这些不是新增的 `PI-000` blocker；若它们属于最终发行格式，仍必须在
  `PI-150` 以实际 release artifact 验收。
- 已发布包的 shrinkwrap 是 production-only，但 package root 仍列出 10 个
  devDependencies；npm 11 的直接 `ci --omit=dev` 会在 omit 前因不同步失败。
  当前资格 probe 只在临时副本移除该字段后复用原 shrinkwrap。`PI-030`
  必须把永久 staging 处理定义为显式、可复现的实现与验收项，不能把临时
  workaround 当成最终打包已通过。
- `PI-150` 的 macOS handoff 要求 x64/arm64 各使用独立 checkout、对应架构
  Node/Electron download 与 frozen install，依次运行 workspace 5+5、staged
  5+5、controlled packaged 5+5、packaged loopback、closure/native/resource
  检查和 metrics，再验证最终目标 artifact；不得跨架构复用 `node_modules`
  或 artifact。`PI-000` waiver 不得在 `PI-150` 被当作证据。
- 当前执行环境没有仓库 CI definition、macOS runner/SSH host、GitLab runner
  CLI 或 Provider credential environment variable。internal GitLab remote 只能
  提供源码远端，不能生成真实 Provider 证据，也不能提前补齐 `PI-150` 延期的
  macOS 证据；前者已由用户接受为非阻断风险，后者仍将在 release stage 阻断
  `PI-150`。

当前 QG 状态（编号严格以 `ML-CODE-PI-001` 第 8.1 节为准；实施证据中的
task-local 状态表不是规范编号来源）：

| Gate | 状态 | 规划解释 |
| --- | --- | --- |
| `QG-001` | Pass | 精确 identity、pin、engine、CLI 已确认 |
| `QG-002` | Pass | 修订后的 Phase-0 平台范围为 Windows x64 + Linux x64；两者 packaged qualification artifact 的 spawn/RPC/session/prompt/abort/settle/reopen/exit 已通过。macOS x64/arm64 Explicitly Waived / Deferred，不是 Pass |
| `QG-003` | Pass | 修订后的 Phase-0 平台范围内，Windows/Linux controlled qualification artifact 的完整适用 package、WASM/native asset 可解析；最终产品 artifact 与 macOS 实跑留在 `PI-150` |
| `QG-004` | Explicitly Waived / Accepted Risk | 不是 Pass。Windows/Linux packaged 四协议 loopback 合同通过且 `realTurnVerified=false`；真实 Account/auth/endpoint/proxy/rate-limit/response variance 与真实 base URL/header/environment credential/model/image 兼容未验证，由用户接受风险 |
| `QG-005` | Explicitly Waived / Accepted Risk | 不是 Pass。provider-shaped loopback two-worker overlap/单侧 abort 通过；真实 provider 并发或串行/限流及跨 worker abort/event/session/model/credential 隔离未验证，由用户接受风险 |
| `QG-006` | Pass | 修订后的 Phase-0 平台范围内，Windows/Linux cold/warm/RSS/exit 的 p50/p95/max 与样本数已报告；macOS metrics Explicitly Waived / Deferred 到 `PI-150`，不是 Pass |
| `QG-007` | Pending / 未触发 | 尚无已确认失败；只有未豁免的 packaging/provider-shaped contract/concurrency/abort/预算门确认失败才触发 utility-process SDK 修订。用户 waiver 不是失败 |

规划判断：逐项审计 `PI-000` Required work、Acceptance 与 Stop condition 后，
所有未豁免要求均已有证据且没有已确认失败。macOS Phase-0 明确 deferred 到
`PI-150`；`QG-004`/`QG-005` 明确 Accepted Risk；两类均不是 Pass。`QG-007`
保持 Pending / not triggered。因此 `PI-000` 标记为 **Done with explicit
waivers**。按未修改的 DAG 重新计算，精确新 Ready Frontier 是 `PI-010`、
`PI-020`、`PI-030`。真实外部 Provider 不再是 `PI-000`/`PI-150`/release
blocker；macOS x64/arm64 在 `PI-150` 仍是不可豁免的 release blocker。若未来
任何未豁免的 packaging、provider-shaped contract/concurrency/abort 或预算门
出现确认失败，继续按 Stop condition 修订为 SDK-in-Electron-utility-process；
仍禁止 OpenCode fallback 或 RPC/SDK 双生产路径。

## 1. 执行规则

1. 所有产品代码票据属于同一个 OpenCode → Pi 硬切换 release unit。中间提交可以存在新旧源码，但任何部分不得以双 runtime 形式发布。
2. `PI-000` 是阻断式资格门；当前已 Done with explicit waivers。任何历史或未来执行中，它未完成前仍不得开始会制造迁移成本的产品实现；本图将所有实施票据显式依赖它。
3. 只有依赖全部 `Done` 的票据才进入 Ready Frontier。依赖不满足时，不得以“先写一点”绕过。
4. 每张票据只拥有其“主要文件/责任区”。共享文件必须由依赖更靠前的票据定义合同，后续票据按合同消费；需要改变合同必须先更新上游测试和关联 Spec。
5. 一张票据只有在自身 acceptance 和 verification 全部通过后才能标 `Done`。仅编译、仅单测、仅人工体验均不充分。
6. `PI-000`～`PI-150` 构成一个实施分支/PR 的完整代码范围；不得把未删除 OpenCode 的中间状态合入 release。
7. `PI-160` 是终端 Integration/Release Gate。它在实现 PR 完成后执行最终审阅、集成、canonical promotion 和发布阻断检查。
8. 本票据图不要求任何特定协作方式。当前文档任务按用户要求不创建子智能体；未来执行也必须遵守当时用户和仓库并发所有权规则。

## 2. 依赖图

```mermaid
flowchart TD
  P000[PI-000 Runtime qualification gate]
  P010[PI-010 Conversation contracts & reducer]
  P020[PI-020 Schema v2 & migration]
  P030[PI-030 Pi process/RPC foundation]
  P040[PI-040 Provider & managed resources]
  P050[PI-050 Worker pool & session registry]
  P060[PI-060 Event projector & hydration]
  P070[PI-070 Extension host, interactions & lease]
  P080[PI-080 Subagent scheduler]
  P090[PI-090 Product tools & change tracker]
  P100[PI-100 Core /api/coding Host API]
  P105[PI-105 Files/changes/skills Host API]
  P110[PI-110 Renderer protocol store]
  P120[PI-120 Core Chat & first-Conversation UX]
  P130[PI-130 Feature-complete Coding UI]
  P140[PI-140 OpenCode removal & cutover migration]
  P150[PI-150 Packaging, E2E & performance release proof]
  P160[PI-160 Integration and release gate]

  P000 --> P010
  P000 --> P020
  P000 --> P030
  P020 --> P040
  P030 --> P040
  P010 --> P050
  P020 --> P050
  P030 --> P050
  P040 --> P050
  P010 --> P060
  P050 --> P060
  P060 --> P070
  P040 --> P070
  P070 --> P080
  P070 --> P090
  P020 --> P090
  P020 --> P100
  P060 --> P100
  P070 --> P100
  P020 --> P105
  P090 --> P105
  P010 --> P110
  P100 --> P110
  P110 --> P120
  P080 --> P130
  P090 --> P130
  P105 --> P130
  P120 --> P130
  P130 --> P140
  P140 --> P150
  P150 --> P160
```

## 3. 票据总览

| ID | 标题 | Depends on | 主要责任区 | 完成后解锁 |
| --- | --- | --- | --- | --- |
| `PI-000` | Runtime qualification gate | — | 精确版本、packaged probe、Provider/并发/RSS 证据 | `010`, `020`, `030` |
| `PI-010` | Conversation contracts & reducer | `000` | shared contracts、fixtures、in-memory runtime | `050`, `060`, `110` |
| `PI-020` | Schema v2 & migration | `000` | `coding-projects`、project/conversation schema、backup | `040`, `050`, `090`, `100`, `105` |
| `PI-030` | Pi process/RPC foundation | `000` | bundler、worker process、LF framer、RPC client | `040`, `050` |
| `PI-040` | Provider & managed resources | `020`, `030` | provider catalog、secret、prompt/skill/resource loader | `050`, `070` |
| `PI-050` | Worker pool & session registry | `010`, `020`, `030`, `040` | runtime、pool、registry、lifecycle、telemetry base | `060` |
| `PI-060` | Event projector & hydration | `010`, `050` | live assembly、active leaf、snapshot/reconcile/recover | `070`, `100` |
| `PI-070` | Extension host, interactions & lease | `040`, `060` | managed extension bridge、ask_user、write lease | `080`, `090`, `100` |
| `PI-080` | Subagent scheduler | `070` | `subagent.v1`、child process、caps、abort | `130` |
| `PI-090` | Product tools & change tracker | `020`, `070` | browser/game/task/changed-file/skills、change tracker | `105`, `130` |
| `PI-100` | Core `/api/coding` Host API | `020`, `060`, `070` | project/conversation routes、SSE、interactions | `110` |
| `PI-105` | Files/changes/skills Host API | `020`, `090` | file/search/change/skill routes | `130` |
| `PI-110` | Renderer protocol store | `010`, `100` | typed facade、per-Conversation store、snapshot/patch | `120` |
| `PI-120` | Core Chat & first-Conversation UX | `110` | Composer、timeline、optimistic prompt、render batching | `130` |
| `PI-130` | Feature-complete Coding UI | `080`, `090`, `105`, `120` | model/thinking/queue/compaction/interactions/subagents/changes | `140` |
| `PI-140` | OpenCode removal & cutover migration | `130` | 删除旧 runtime/routes/deps/UI/tests/resources、migration notice | `150` |
| `PI-150` | Packaging, E2E & performance proof | `140` | artifact、real smoke、full E2E、Windows/Linux/macOS x64+arm64、perf report | `160` |
| `PI-160` | Integration and release gate | `150` | final review、zero residue、canonical docs、release decision | Release |

## 4. Ready Frontier 演进

下面是依赖完成后的预期 frontier，不是必须串行执行的阶段清单：

| 条件 | 新 Ready Frontier |
| --- | --- |
| 初始，以及 `PI-000` 完成前 | `PI-000`（唯一 frontier；未 Done，无下游解锁） |
| 2026-08-22 `PI-000` Done with explicit waivers | `PI-010`, `PI-020`, `PI-030` |
| `PI-020` + `PI-030` Done | `PI-040`（同时等待中的 `PI-010` 可继续） |
| `PI-010` + `PI-020` + `PI-030` + `PI-040` Done | `PI-050` |
| `PI-050` Done | `PI-060` |
| `PI-060` Done | `PI-070`；`PI-100` 仍等 `PI-070` |
| `PI-070` Done | `PI-080`, `PI-090`, `PI-100` |
| `PI-090` Done | `PI-105` |
| `PI-100` Done | `PI-110` |
| `PI-110` Done | `PI-120` |
| `PI-080` + `PI-090` + `PI-105` + `PI-120` Done | `PI-130` |
| `PI-130` Done | `PI-140` |
| `PI-140` Done | `PI-150` |
| `PI-150` Done | `PI-160` |

## 5. 票据详情

## PI-000 — Runtime qualification gate

### Objective

在写业务迁移前，证明选定 Pi 版本能在 Makelore qualification 打包边界中满足 runtime、四协议 packaged loopback/provider-shaped 并发、资源和退出要求；对明确未验证的真实外部 Provider 风险作出显式人类决定，确认失败时尽早终止错误架构。

### Dependencies

- None。

### Current planning status

- **Done with explicit waivers**；实施任务为
  `20260822-pi-runtime-qualification-c52e8a14`。这不是全部 QG Pass。
- Windows x64 与 WSL2 Linux x64 的 workspace/staged/controlled packaged RPC、
  session、process、closure、loopback 四协议合同与预算证据通过；受控 artifact
  不是最终 bundler 或 release installer。
- 用户于 2026-08-22 将 macOS x64/arm64 明确标记为 **Explicitly Waived /
  Deferred** for `PI-000`。packaged resource path defect 已修并通过 focused path
  test 与 Windows actual regression，但 macOS 没有实跑、不是 Pass；workspace/
  staged/controlled packaged/loopback/metrics 全部移交 `PI-150`。
- 用户于 2026-08-22 明确接受四协议真实 Provider Account/兼容与真实双 worker
  并发/隔离风险，`QG-004`、`QG-005` 为 Explicitly Waived / Accepted Risk，
  不是 Pass。loopback 不得被归类为 Provider Account qualification，报告保持
  `realTurnVerified=false`。
- Linux 最终 release artifact 与 macOS 全套实跑属于 `PI-150`；macOS 仍是
  release blocker。当前 `PI-000` 无剩余 Phase-0 blocker，已解锁 `PI-010`、
  `PI-020`、`PI-030`。

### Owns

- 精确 Pi version/tag/commit 决策。
- 最小 package pin 与 lockfile 变更。
- 最小 `scripts/probe-pi-runtime.*`、临时/受控 packaged probe、结果报告。
- 资格证据，不拥有最终 Chat、Host route 或迁移实现。

### Required work

1. 复核候选 `@earendil-works/pi-coding-agent@0.84.2`；锁定确切 package version、CLI entry、Node engine、RPC/session docs 对应 tag/commit。
2. 以 Electron Node 在 Phase-0 平台范围 Windows x64、Linux x64 的 unpackaged 与 packaged qualification seam 启动 RPC。
3. 验证 `get_state`、persistent session create/open、prompt accepted、abort、`agent_settled`、reopen、clean shutdown。
4. 从 frozen dependency graph stage Windows x64、Linux x64 的最小完整 production closure，验证 packaged qualification artifact 的 WASM/native/optional resources；最终产品 artifact 留给 `PI-150`。
5. 用 Windows/Linux packaged loopback 覆盖所有受支持协议的 base URL/path、headers、environment credential plumbing、模型、图片 request/SSE 合同；记录真实外部 Provider Account 验证已 Explicitly Waived / Accepted Risk，`realTurnVerified=false`。
6. 两个独立 worker 同时运行 provider-shaped loopback turn，证明受控时间窗口重叠、单侧 abort 与另一侧 settled；记录真实 provider 并发/串行/限流及跨 worker abort/event/session/model/credential 隔离为 Accepted Risk。
7. 在 Windows x64、Linux x64 运行 cold/warm/RSS/exit samples，报告 p50/p95/max、样本数、平台和 artifact 状态。
8. 明确 `AGENTS.md`/context、offline、trust、resource discovery、shell 的锁定版本行为。

macOS x64/arm64 在本票据中 Explicitly Waived / Deferred by user on
2026-08-22；这不是平台通过证据。对应 workspace/staged/controlled packaged/
loopback/metrics 工作由 `PI-150` 接管。

### Closure audit（2026-08-22）

| Required work | 审计状态 | 依据 |
| --- | --- | --- |
| 1. identity/pin/engine/entry | Pass | Pi 0.84.2、tag/commit、CLI、Electron Node engine 与 frozen lockfile 已确认 |
| 2. platform process seam | Pass + explicit macOS deferral | Windows x64 与 Linux x64 workspace/staged/controlled packaged 已通过；macOS x64/arm64 不是 Pass，转 `PI-150` |
| 3. session/RPC lifecycle | Pass | get_state、create/open、prompt accepted、abort、settled、reopen、clean shutdown 已通过 |
| 4. production closure/assets | Pass | Windows/Linux 适用 packages、WASM/native/optional assets 在 qualification artifact 可解析；最终 artifact 留 `PI-150` |
| 5. protocol compatibility | Explicitly Waived / Accepted Risk；替代 smoke Pass | 四协议 packaged loopback 的 base URL/path/header/environment credential plumbing/model/image request/SSE 已通过；真实外部 Provider 未验证且 `realTurnVerified=false` |
| 6. two-worker concurrency/isolation | Explicitly Waived / Accepted Risk；替代 smoke Pass | provider-shaped two-worker overlap、单侧 abort、另一侧 settled 与受控路由已通过；真实 provider 行为未验证 |
| 7. latency/RSS/exit budgets | Pass | Windows/Linux cold/warm/RSS/exit 样本与 p50/p95/max 已记录并满足预算 |
| 8. context/offline/trust/resources/shell | Pass | 锁定版本以 explicit no-discovery/no-context/no-approve/offline flags 运行，shell 与 abort 行为已验证 |

审计未发现除上述两类显式 waiver 外的未完成 Required work。Acceptance 的
非豁免证据均成立，Stop condition 没有已确认失败，因此 `QG-007` 不触发。

### Acceptance

- Spec `QG-001`、`QG-002`、`QG-003`、`QG-006` 在修订后的 Phase-0 平台范围内有可重复证据；`QG-004`、`QG-005` 有明确人类 waiver、完整风险记录和不可误标 Pass 的证据状态。
- cold `rpc.ready` p95 ≤ 3,000 ms；warm p95 ≤ 1,500 ms；10 秒 operational deadline 内确定性失败。
- 两 worker packaged provider-shaped loopback turn 重叠；一个 worker abort/crash 不改变另一个受控状态。真实外部 Provider turn 不属于 hard gate。
- 完整 dependency closure 从 Windows/Linux packaged qualification artifact resolve，退出无遗留 Pi child；最终产品 artifact closure 属于 `PI-150`。
- Packaged loopback matrix 覆盖当前实际支持的每种协议类型；真实外部 Account 兼容保持 `realTurnVerified=false` 和 Accepted Risk，不 silently fallback 或伪报 Pass。
- 精确 pin，不使用 `^`/`~`。
- macOS waiver 只允许 `PI-000` 不等待该平台，既不构成 macOS Pass，也不满足 `PI-150` 的 cross-platform acceptance。
- `QG-004`/`QG-005` waiver 只移除真实外部 Provider hard gate；Windows/Linux 及最终 artifact 的 packaged loopback/provider-shaped overlap/abort smoke 仍必须通过。

### Stop condition

若修订后 Phase-0 范围内未豁免的 packaging、provider-shaped contract/concurrency/abort 或预算不通过：本票据保持或重新进入 Blocked，停止后续实现。只能通过修订 Spec/ADR 选择“Pi SDK in Electron utility process”后重新验收；不得引入 OpenCode fallback 或 RPC/SDK 双生产路径。缺少已豁免的真实外部 Provider 样本不是失败，不触发 `QG-007`。延期的 macOS 验证若在 `PI-150` 失败，则必须阻断 release 并返工或修订架构，不得以本 waiver 放行。

### Verification

- Probe command 和结果可以在干净安装依赖后重跑。
- artifact dependency resolve verifier。
- 两 worker packaged provider-shaped loopback overlap/abort smoke；结果明确 `realTurnVerified=false`。
- process-tree clean-exit 检查。

## PI-010 — Conversation contracts and reducer

### Objective

先固化 vendor-neutral Conversation 领域协议，使 Main、Renderer 和测试不再围绕 OpenCode/Pi wire 结构耦合。

### Dependencies

- `PI-000`。

### Owns

- `electron/coding-runtime/contracts.ts` 或 shared 等价位置。
- `ConversationSnapshot`、`ConversationPatchEnvelope`、node/run/queue/context/interaction/model/error DTO。
- 统一 normalization reducer。
- `InMemoryConversationRuntime`。
- 锁定 Pi 版本的 wire fixture → product fixture 边界定义。

### Required work

1. 实现 Spec 第 5、10 节全部公开类型，公共 export 不导入 Pi/OpenCode。
2. reducer 支持 snapshot replace、严格 generation/seq、gap invalidation、message/block/tool/queue/interaction/compaction/subagent/context ops。
3. UI ID 与 durable source ID 分离；optimistic user node 通过 `clientRequestId` reconcile。
4. 用同一个 reducer 处理 live fixture 和 hydrated fixture。
5. 实现 in-memory runtime，供 Renderer/Host product tests 使用。
6. 明确 unknown op/schema 的 fail-closed 行为。

### Acceptance

- 混合 text/thinking/tool、parallel tools、tool error、retry、compaction willRetry、queue、interaction、subagent、unknown custom fixture 全通过。
- seq gap 只 invalidates 目标 Conversation；旧 generation patch 被丢弃。
- `toolResult` 不成为 message；cumulative tool output 不重复。
- `agent_end` fixture 不产生 idle；`agent_settled` 才产生 idle。
- Renderer contract test 没有任何 Pi/OpenCode import。

### Verification

- Focused contract/reducer unit tests。
- Type-level no-vendor import check 或 scoped `rg` assertion。
- Snapshot → patches → snapshot equivalence fixture。

## PI-020 — Project and Conversation schema v2 migration

### Objective

把项目/伙伴/Conversation 产品数据从 OpenCode runtime identity 中解耦，并保证一次性迁移可回退、不会误删用户数据。

### Dependencies

- `PI-000`。

### Owns

- `electron/coding-projects/project-config.ts`。
- `project-store.ts`、`conversation-store.ts`、migration/backup helpers。
- schema v2 types/tests。
- 项目、伙伴、空 Conversation 的 local-only create flow。

### Required work

1. 定义 project schema v2 `ProductModelRef` 和 model unresolved 状态。
2. 定义 Conversation schema v2、产品 UUID、optional Pi binding、opaque sessionKey。
3. 实现 schema v1 backup → model mapping → v2 atomic write。
4. 无唯一 model mapping 时保留 Agent，标记用户选择；禁止默认模型。
5. v1 Conversation metadata 备份后初始化空 v2，不将旧 OpenCode Session 放入 sidebar。
6. 只清理已证明未修改的 generated `.opencode/agent`；uncertain/modified 移到 backup。
7. project/partner/Conversation create 不调用 runtime。

### Acceptance

- stable Agent ID/name/prompt/skills/archive 完整保持。
- 无 backup 时绝不覆写 v1；任意写失败保留可重试原状态。
- `sessionKey` path traversal/absolute path 被拒绝。
- 两个并发首发只建立一个 Pi session binding（通过 store single-flight contract fixture；实际 runtime 在后续票据接入）。
- 旧 Conversation 不显示；一次性 notice 状态可被 UI 后续消费。
- userData/opencode 和不确定 `.opencode` 内容未被递归删除。
- 项目、伙伴、Conversation metadata 性能可单独测量，且无 child process。

### Verification

- Migration table tests：unique/unresolved/no-account/corrupt write/retry/modified Agent file。
- Atomic persistence tests。
- Local-create integration test with spawn spy = 0。

## PI-030 — Pi process and RPC foundation

### Objective

提供可打包、可测试、可恢复的 Pi child process/RPC 底座，不掺入项目 CRUD 或 Renderer 逻辑。

### Dependencies

- `PI-000`。

### Owns

- `electron/coding-runtime/pi/worker-process.ts`。
- `rpc-framer.ts`、`rpc-client.ts`、process errors。
- 初版 `scripts/bundle-pi-runtime.mjs` 与 runtime manifest。
- programmable fake Pi child test fixture。

### Required work

1. Electron Node + `ELECTRON_RUN_AS_NODE=1` 启动锁定 Pi entry。
2. 显式 offline/no-approve/no-auto-resource 参数；stdout RPC only、stderr log only。
3. 自有 strict LF framer，支持 chunk 边界和 U+2028/U+2029。
4. command ID correlation、out-of-order response、event dispatch、timeout/AbortSignal。
5. malformed/oversized stdout、unexpected exit、stderr sanitizer、backpressure。
6. process graceful shutdown 3 秒 + forced kill，确保整个 child tree 清理。
7. stage 完整 production closure 与 manifest。
8. 为已发布 Pi package 的 production-only shrinkwrap 与 root 10 个
   devDependencies 不同步选择并测试一个显式、可复现的永久 staging 机制；
   不把 `PI-000` 临时副本处理或受控 Electron Builder probe 直接当成最终
   bundler。artifact verifier 按可解析 package/version/asset 验证 closure，
   不把 Electron Builder 的同版本依赖扁平化误判为缺失。

### Acceptance

- Spec `RPC-001`～`RPC-005` 全部通过。
- stdout 任意非 JSONL 导致目标 worker protocol error，不污染其他 worker。
- pending command 在 exit/abort/generation invalidation 时全部 settle，无 promise leak。
- prompt 类 command timeout 不自动重发。
- fake child 可脚本化输出 response/event/crash/partial line/large line，供后续 Main integration 使用。
- bundler 在 frozen install 上确定性生成相同 manifest 内容（不要求额外 checksum 文件）。
- 永久 staging 能在 npm 11 下从发布 package/shrinkwrap 可重复生成 production
  closure，且测试覆盖 root devDependencies 不同步与同版本 nested-to-root
  flattening；不依赖开发机已有 `node_modules` 或受控 probe 的临时目录。

### Verification

- Focused process/RPC unit tests。
- Real Pi `get_state` protocol smoke。
- Packaged entry load/exit smoke。

## PI-040 — Provider and managed resources

### Objective

把当前 Provider Account、Works gateway、credential、伙伴 prompt 和 skills 映射为锁定 Pi 版本的受管输入，同时保持 Main-owned secret/trust 边界。

### Dependencies

- `PI-020`。
- `PI-030`。

### Owns

- `electron/coding-runtime/pi/provider-config.ts`。
- `resource-loader.ts`、prompt/Agent manifest cache。
- `resources/coding-skills` 与 registry 映射。
- Provider revision/staleness contract。

### Required work

1. 实现 `PiProviderDescriptor` 和 account → runtime catalog 投影。
2. 迁移 Works `/v1`、proxy token、custom header/base URL 语义。
3. credential 只通过 worker environment/受管 provider 注入，完整日志脱敏。
4. account refresh single-flight；认证恢复最多一次。
5. provider/resource revision：idle stale 下次 prompt 前重建，running settled 后重建。
6. 生成受管伙伴 prompt/Agent manifest，不生成 `.pi/agents`。
7. 移动内建 skills 到 vendor-neutral resources，仅显式传 selected paths。

### Acceptance

- 当前支持的每种 Provider Account/协议配置 fixture 都能构建有效 catalog，并通过
  packaged provider-shaped loopback 完成 prompt/settled；真实外部 Provider prompt
  保持可选、非阻断，未取得证据时 `realTurnVerified=false`。
- 两个同 vendor account 的 runtime ID 不冲突。
- model/image capability 校验准确；不可用模型原子失败。
- token/header/prompt 内容不出现在 argv、snapshot、SSE、Renderer、diagnostics 或 test snapshot。
- 项目/用户 `.pi` resources 不被自动加载。
- provider revision 不打断 running run；settled 后才重建。

### Verification

- Provider catalog fixtures。
- Secret-redaction tests over argv/env-safe projection/stderr/API DTO。
- Resource discovery negative tests。
- Packaged provider-shaped loopback smoke from qualification matrix；可选 real account
  smoke 只能作为非阻断诊断，不得把 waiver 改写为 Pass。

## PI-050 — Worker pool and session registry

### Objective

实现一 Conversation 一 worker 的真实并发、session 持久绑定、资源调度和生命周期隔离。

### Dependencies

- `PI-010`。
- `PI-020`。
- `PI-030`。
- `PI-040`。

### Owns

- `electron/coding-runtime/pi/runtime.ts`。
- `worker-pool.ts`、session registry、permit queue、idle LRU。
- prepare/prompt/queue/abort/model/thinking/compact/fork/dispose lifecycle orchestration。
- telemetry base/span correlation。

### Required work

1. per-Conversation `prepare` single-flight 和 lazy session open/create。
2. worker state machine、generation、pending commands/interactions/children references。
3. top-level running cap 4、warm idle cap 4、total process soft cap integration。
4. running 不 eviction，idle LRU，app quit shutdown。
5. prompt/steer/follow-up acceptance，不等待 settle。
6. abort/model/thinking/compact/fork/recover/dispose 目标隔离。
7. Provider/resource stale 在安全边界重建。
8. `worker.queue_wait/spawn/rpc.ready/session.open/resources.ready/prompt.accepted` telemetry。

### Acceptance

- 一 worker 永不并行承载两个 Conversation。
- 第 5 个 top-level run 进入自己的 queue；前四个 settled 后按公平顺序继续。
- running worker 不被 LRU kill；idle 超限准确 eviction/reopen。
- crash generation 清理 pending RPC/permit/interaction/child reference，并不影响其他 worker。
- prompt HTTP/RPC acceptance 与 run completion 分离。
- model/thinking 只改变目标 Conversation；不可用模型不改变旧状态。
- app quit 3 秒后无遗留 parent worker。

### Verification

- Worker-pool focused tests：single-flight、caps、fair queue、LRU、crash、quit、stale revision。
- Two-worker fake + packaged provider-shaped loopback concurrent run integration；真实外部 Provider 非阻断且不得写成已验证。
- Process-tree cleanup test。

## PI-060 — Event projector, hydration, and recovery

### Objective

把 Pi live RPC 和 persisted session tree 正确投影为 Makelore Snapshot/Patch，解决 streaming identity、active branch、settled reconciliation 和恢复。

### Dependencies

- `PI-010`。
- `PI-050`。

### Owns

- `event-projector.ts`。
- `session-projector.ts`。
- attachment projection hooks。
- snapshot creation、durable reconcile、recover orchestration integration。

### Required work

1. 按 `contentIndex` 组装 text/thinking/toolcall；`message_end` 权威替换。
2. cumulative `partialResult` replace；`toolResult` attach tool card。
3. run/turn/retry/compaction/queue/interaction/usage/context 映射。
4. `agent_end` checkpoint、`agent_settled` idle。
5. entries + leafId + parentId active path hydration；废弃分支排除。
6. live UI ID 与 durable entry ID reconcile。
7. generation/seq envelope、gap invalidation、snapshot rebuild。
8. unknown/custom bounded diagnostics、large image attachment ref。
9. recover：旧 generation close、资源清理、reopen、hydrate、新 snapshot。

### Acceptance

- Spec 第 10、11、18 节 event/session/failure 规则全部有 fixture。
- live run 完成后的 Snapshot 与从 session 冷 hydrate 的 Snapshot 等价。
- compaction `willRetry` 不 idle；queue continuation 不提前释放 permit。
- abandoned branch 永不进入 active timeline。
- tool partial output 不重复；camel-case `toolResult` 不变 assistant。
- SSE gap/recover 只替换目标 Conversation。
- unreadable session 保留原文件并进入 recoverable error，不自动截断。

### Verification

- Projector/session unit fixtures from exact Pi version。
- Fake Pi end-to-end run → settle → reopen comparison。
- Small real Pi drift smoke。

## PI-070 — Managed extension host, interactions, and write lease

### Objective

建立唯一受管 extension entry、最小 child→Main seam、用户 interaction 和同项目 mutation lease。

### Dependencies

- `PI-040`。
- `PI-060`。

### Owns

- `extensions/makelore-runtime.ts`。
- extension internal endpoint/IPC bridge 与 worker token registry。
- `interaction.ts`、`write-lease.ts`。
- interaction Host-side store and projector integration。

### Required work

1. 只显式加载一个 versioned extension bundle。
2. 每 worker loopback/IPC token，dispose/recover 后失效。
3. 验证 conversationId/generation/runId 与 worker registry。
4. `ask_user` select/confirm/input/editor；notify/status/widget/title/editor-text 安全投影。
5. 同项目 mutation write lease、可取消等待、所有终态释放。
6. worker crash/abort 清理 interaction/lease。
7. unknown UI/widget/details 只诊断，不 raw dump。

### Acceptance

- 项目/用户第三方 Pi extension 不会被加载。
- 伪造旧 generation/token 的 request 被拒绝且不影响当前 worker。
- interaction response 严格按 ID；crash/abort 后全部 cancelled。
- 同项目 mutation 串行；不同项目并行；read-only 不等待 lease。
- complete/error/abort/timeout/crash 全部释放 lease，无永久占用。
- Textarea draft revision 已变化时 `set_editor_text` 不覆盖。

### Verification

- Extension integration tests through real bridge, not direct function-only mocks。
- Lease concurrency/cancellation matrix。
- Interaction lifecycle and stale-token tests。

## PI-080 — Subagent scheduler and nested protocol

### Objective

用 Makelore-owned `subagent.v1` 实现多 child Pi 调度，不依赖官方示例的非稳定 GUI details。

### Dependencies

- `PI-070`。

### Owns

- `extensions/subagent.ts`。
- child process supervisor、global semaphore、parent-child registry。
- `subagent.v1` schema/projector fixtures。

### Required work

1. `single`、`parallel`、`chain` dispatch validation；单次最多 8 tasks。
2. 每 child 独立 Pi process/context，使用受管 Agent manifest/model/tool profile。
3. 全应用最多 4 running child，和 parent process 组成 soft cap 8。
4. read-only/coding tool profile；coding child 接入 write lease。
5. parent abort/crash 传播 child；child exit 清理 permit。
6. parallel 保留其他完成结果；chain 首失败停止并标 skipped。
7. nested progress/details 只输出 `subagent.v1`。

### Acceptance

- 1、4、8 tasks 的 single/parallel/chain fixture 正确；第 9 个 schema validation 拒绝。
- 两个 parent 争用全局 child semaphore 时总 running child ≤ 4。
- parent abort 后无 child orphan；permit 全释放。
- 一个 parallel child failure 不删除其他 summary/usage；chain 后续标 skipped。
- unknown schema/version 不崩 UI、不 dump raw JSON。
- 同项目 coding child 与 parent mutation 遵守同一 lease。

### Verification

- Fake child scheduler integration tests。
- One real subagent child packaged smoke。
- Process-tree and semaphore leak check。

## PI-090 — Product tools and Conversation change tracker

### Objective

迁移 Makelore 真实使用的 browser、game asset、task/changed-file 和 skill 能力，并以 Main-owned tracker 替代 OpenCode Session diff。

### Dependencies

- `PI-020`。
- `PI-070`。

### Owns

- `extensions/agent-browser.ts`、`game-assets.ts`、`task-state.ts`、`changed-file.ts`。
- `electron/coding-projects/skill-registry.ts`。
- `conversation-change-tracker.ts`。
- Main browser/attachment integration at the existing seam。

### Required work

1. `agent_browser` extension 直连现有 Main browser service；删除对 MCP 的运行时依赖。
2. 迁移现有 game asset browse/review 产品语义，不复制 OpenCode plugin API。
3. `task_state` 使用版本化 typed details；不暴露旧 todos endpoint。
4. `changed_file` 上报 relative touched paths。
5. run start 记录 git head/status baseline；settled 后刷新 status/diff，bash 触发 project-level refresh。
6. 只读 changed path diff；untracked 有界 preview；无 per-file hash/checkpoint。
7. selected skills registry 与 command catalog 安全投影。

### Acceptance

- browser tool 不启动 `@playwright/mcp`/MCP child，screenshot 使用 attachment ID。
- game asset/product tool 有 real/fake integration coverage。
- changes panel 数据不来自 Pi message 文本猜测。
- write/edit touched path 精准刷新；bash 后能发现未上报改动。
- untracked preview 有界且无绝对路径。
- fork UI 不暗示文件回滚。
- 没有为 diff 增加 hash/checkpoint framework。

### Verification

- Browser/game tool packaged smoke。
- Git/no-git/dirty/untracked/bash change tracker tests。
- Skill command and explicit-path tests。

## PI-100 — Core `/api/coding` Host API

### Objective

用产品域 Host API 连接 project/conversation service、runtime Snapshot/Patch 和 interactions，完全移除 Renderer 对 OpenCode route contract 的依赖。

### Dependencies

- `PI-020`。
- `PI-060`。
- `PI-070`。

### Owns

- `electron/api/routes/coding-projects.ts`。
- `electron/api/routes/coding-conversations.ts`。
- `/api/coding/events` SSE。
- interactions route、runtime diagnostics 安全投影。
- Renderer typed facade 的 Main contract half。

### Required work

1. 实现 Spec 第 12.1 节除 files/skills/changes 外的核心 routes。
2. prompt/steer/follow-up 返回 HTTP 202 acceptance；不等待 settle。
3. `clientRequestId` bounded dedupe 与 uncertain request 行为。
4. SSE envelope、per-Conversation seq/generation、snapshot-first reconnect。
5. request validation、conversation/project ownership、sanitized errors。
6. diagnostics 只给 worker state/revision/stage summary，无 secret/absolute session path。
7. interactions list/respond ID correlation。

### Acceptance

- Renderer-facing core route 中不出现 `/api/opencode` 或 Pi wire field。
- project/partner/Conversation create route 不启动 runtime。
- prompt 202 在 provider first token/settled 前返回。
- seq gap test 只 GET 目标 snapshot；SSE reconnect 不重发 prompt。
- duplicate accepted `clientRequestId` 返回相同 acceptance；uncertain mutation 不二次发送。
- raw stderr/provider/extension path/credential 不穿透。

### Verification

- Route contract tests with in-memory and fake Pi runtime。
- Host API → SSE → snapshot integration。
- Error redaction and timeout tests。

## PI-105 — Files, changes, skills, and command Host API

### Objective

提供 vendor-neutral project file、search、changes、skills 和 command API，使 Renderer 不再依赖 OpenCode 的文件/Session diff/todo 路由。

### Dependencies

- `PI-020`。
- `PI-090`。

### Owns

- `electron/api/routes/coding-files.ts`。
- file/status/find/content/search facade。
- Conversation changes、skills、commands route integration。
- Renderer typed facade 的 file/tool catalog contract half。

### Required work

1. 迁移现有受支持 file status/find/content/search 行为到 product service。
2. 所有 path 相对 active project，保持现有内容/搜索边界。
3. expose Conversation changes snapshot，不 expose Pi/session diff。
4. 合并 Pi extension/skill commands 与 Makelore commands，稳定 DTO。
5. 删除 todos/revert/unrevert/share 相关 API 外形。

### Acceptance

- Renderer 无绝对项目路径和任意 filesystem proxy 能力。
- files/search 行为与现有受支持 UX 等价。
- changes 与 target Conversation/run 关联，数据来自 tracker。
- skills/commands 只包含显式受管资源。
- route/type/test 中无旧 todos/share/revert contract。

### Verification

- Focused file/search/change/command route tests。
- Path boundary and redaction tests。
- Renderer facade contract tests。

## PI-110 — Renderer Snapshot/Patch store

### Objective

建立按 Conversation 分片、可 gap recovery、无 vendor import 的 Renderer 状态层和 typed Host facade。

### Dependencies

- `PI-010`。
- `PI-100`。

### Owns

- `src/stores/coding-conversations.ts`。
- `src/types/coding-conversation.ts` 或 shared re-export。
- `src/lib/coding-conversations.ts`/existing Host API facade integration。
- SSE subscription/reconnect、snapshot loader、draft state。

### Required work

1. 每 Conversation 独立 snapshot/run/error/queue/model/draft/unread/cursor。
2. Snapshot first load + SSE live，generation/seq/gap reducer。
3. hidden Conversation 只更新 lightweight summary。
4. optimistic user node/draft revision/clientRequestId reconciliation。
5. target-only error/recover；top-level error 只用于真实全局错误。
6. Selector 粒度避免 token 时全 store rerender。

### Acceptance

- 两 Conversation simultaneous patch 不串 node/run/error/queue/model/draft。
- seq gap 只刷新目标；旧 generation 丢弃。
- optimistic accept/reject/uncertain state 可恢复 draft/附件。
- hidden Conversation streaming 不触发其 Markdown component render。
- store/facade/types 无 Pi/OpenCode import/name。
- 旧 `src/stores/opencode.ts` 不再被新 UI 读取；实际删除留 `PI-140`。

### Verification

- Store reducer/selector tests。
- Two-Conversation SSE integration。
- Render-count fixture for hidden/current Conversation。

## PI-120 — Core Chat and first-Conversation UX

### Objective

交付 vendor-neutral Chat core，彻底修复首次 Conversation 输入框被全局 runtime/loading 阻塞，并控制流式渲染成本。

### Dependencies

- `PI-110`。

### Owns

- `CodingChatPanel` 核心组合层。
- Composer、message/timeline/tool blocks 的 vendor-neutral components。
- optimistic prompt/recover UI。
- delta batching/attachment preview/render performance。

### Required work

1. Textarea enable rule严格实现 `UX-010`～`UX-014`。
2. create/select Conversation 不等待 runtime；prewarm 仅显示局部状态。
3. first send optimistic node、202 acceptance、preparing/queued/running/error/recover UI。
4. message/thinking/tool/compaction/boundary 基础渲染。
5. 16–33 ms Main batching 的 Renderer局部 block 更新；memo/折叠/虚拟化。
6. attachment ID/preview URL，不持有重复 base64。
7. 组件拆分，避免把旧 4k 行面板机械改名。

### Acceptance

- Runtime/metadata response 被测试故意 hold 时，selected Agent 的 Textarea 仍可输入。
- fresh userData 选择首 Conversation → Composer p95 ≤ 500 ms。
- cold local prepare 超过 10 秒显示 recoverable error，Textarea 仍可编辑。
- prompt accepted 前后 user node不丢；Provider error 不回滚 user message。
- 100 KB cumulative tool/长 thinking 下 Main delta → Renderer commit p95 ≤ 50 ms，输出不重复。
- hidden Conversation 不做全文 Markdown rerender。

### Verification

- Red-capable first-Conversation component test。
- Core Chat focused tests。
- Render commit/IPC payload benchmark fixture。
- First prompt Electron E2E。

## PI-130 — Feature-complete Coding UI

### Objective

在新协议上补齐需要保留的 Code 产品能力和多会话/subagent 交互，使旧 OpenCode UI 可以完整拆除。

### Dependencies

- `PI-080`。
- `PI-090`。
- `PI-105`。
- `PI-120`。

### Owns

- model/thinking controls。
- steer/follow-up queue UI。
- compaction/retry/context UI。
- interactions、subagent nested graph、changes/files/browser/skills/commands UI。
- Conversation fork/title/archive/unread/recover/diagnostics UI。

### Required work

1. model/thinking Conversation setting，与伙伴默认分离。
2. queue 两种 mode、position、等待和 abort。
3. retry/compaction willRetry/settled 正确生命周期。
4. select/confirm/input/editor interactions 与 stale/cancelled 状态。
5. `subagent.v1` nested nodes、parallel/chain error/abort。
6. Conversation changes/file preview、browser attachment、skills/commands。
7. “从这里创建新对话分支”替代 revert 文案，不暗示文件回滚。
8. 删除 share/todo/global runtime controls 的产品入口。

### Acceptance

- 文本、图片、thinking、tools、retry、compaction、queue、interaction、model/thinking、files/changes、browser、skills 全部可在新 UI 使用。
- 两 Conversation 同时 streaming，切换/隐藏/abort/model 互不污染。
- subagent single/parallel/chain nested UI 正确；child error/abort 可理解。
- `agent_end` 不清 busy；`agent_settled` 才释放 queue。
- tool result 不独立 bubble；compaction summary/raw custom details 不泄露。
- share/unshare/revert/unrevert/todos/global runtime controls UI 不存在。

### Verification

- Focused UI tests for every retained/removed behavior。
- Electron E2E：concurrency、model、queue、compaction、interaction、subagent、image、browser/skill、recover。

## PI-140 — OpenCode removal and cutover migration

### Objective

在新链路达到 feature completeness 后，删除所有生产 OpenCode 源码、依赖、route、资源、脚本和旧 UI，并接通最终一次性迁移/提示。

### Dependencies

- `PI-130`。

### Owns

- 删除 `electron/opencode`、OpenCode route/manager/client/materialization/provider/plugin code。
- 删除/重命名 `src/*opencode*`、`shared/opencode-*`、旧 tests/E2E。
- package/lockfile OpenCode 与 MCP dependency removal。
- `.opencode` packaged resources、bundle/smoke script removal。
- 迁移 notice、legacy data inert policy、release-facing removed-feature copy。

### Required work

1. 删除 `/api/opencode/*` 与 Renderer 调用。
2. 删除 `opencode-ai`、`@opencode-ai/plugin`、仅服务 OpenCode 的 `@playwright/mcp`。
3. 删除 manager/client/project-agent-runtime/provider-config/playwright-mcp/plugin materialization。
4. 删除旧 store/types/normalizer/panel/runtime controls/diff preview 和浅 Implementation tests。
5. 删除 share/unshare/revert/unrevert/todos/global runtime controls 的 route/type/test/doc copy。
6. 移动保留的 product skills/assets 到 vendor-neutral 资源。
7. 接通 schema migration、一次性 notice、userData inert/no-read。
8. 保持 app id/protocol/storage identifiers。

### Acceptance

- 生产源码/route/dependency/runtime resource 不包含 OpenCode。
- `rg -i` 只命中明确允许的历史/迁移文本，并逐项分类记录。
- package/lockfile 无 OpenCode package/plugin/MCP dependency。
- 新应用不读取项目 `.opencode` 或 `<userData>/opencode`。
- uncertain/modified `.opencode/agent` 被 backup，未误删。
- stable Agent IDs/app id/protocol/storage 保持。
- 全部 Code UI/Host tests 已指向 `/api/coding` 和新 store。

### Verification

- Zero-residue source/package search。
- Migration E2E from schema v1 fixture。
- Full focused Code tests + typecheck/build before `PI-150`。

## PI-150 — Packaging, E2E, and performance release proof

### Objective

把硬切换打成可发布 artifact，运行完整自动化、真实 Pi、三平台和性能验收，产出可审阅证据。

### Dependencies

- `PI-140`。

### Owns

- 最终 `bundle-pi-runtime`、electron-builder staging、artifact verifier。
- `smoke:pi:real`。
- rewritten/new Electron E2E suite。
- performance harness/report、release note/runbook draft、README current product update。
- feature task verification record与 promotion candidates；canonical docs 留 `PI-160` Integration Gate。

### Required work

1. stage exact Pi production closure、extensions、skills、manifest。
2. artifact verifier 检查 version/engine/resources/resolve/get_state/no-OpenCode/no-dev-path。
3. actual packaged Pi smoke：通过受控 loopback/provider-shaped endpoint 覆盖 session、prompt、tool、abort、settle、reopen、two-worker overlap/isolation、subagent、shutdown；不要求真实外部 Provider Account，报告保持 `realTurnVerified=false`。
4. 完整 typecheck/lint/unit/build/E2E。
5. Windows x64、Linux x64 最终产品 artifact 的 packaged verifier/smoke。
6. 对 macOS x64 与 arm64 分别使用独立 checkout/frozen install，运行 workspace 5+5、staged 5+5、controlled packaged 5+5、packaged loopback、closure/native/resource 检查和 metrics，再验证各自最终目标 artifact；不得用静态 path test、其他平台结果或 `PI-000` waiver 替代。
7. Spec 第 17.3 节全部场景，报告 p50/p95/max/samples/RSS/IPC/commit。
8. release note：旧 Conversation、删除能力、完整版本回退、Pi 新 Conversation 不兼容旧版。
9. README 同步当前 runtime/功能，不写历史迁移日记。

### Acceptance

- `pnpm run typecheck`、`pnpm run lint:check`、`pnpm test`、`pnpm run build:vite`、`pnpm run test:e2e` 全通过。
- artifact verifier 与 real Pi smoke 全通过。
- 最终 packaged 四协议 loopback、provider-shaped two-worker overlap、单侧 abort 与另一侧 settled 全通过；真实外部 Provider waiver 不是 Pass，也不是 release blocker。
- Windows x64、Linux x64、macOS x64、macOS arm64 目标 artifact 与对应验证全部通过；macOS 任一架构缺失即不允许宣称 cross-platform release-ready。
- `PI-000` 的 macOS Explicitly Waived / Deferred 到本票据即失效；延期造成 release-stage packaging/native/resource/performance 返工的风险已经接受，但任何实际失败仍必须阻断 release。
- Composer、worker、acceptance、render p95 全达 Spec 预算。
- 4 parent + 4 child 压力下 UI 可交互，无 orphan process/permit/lease。
- 最终 artifact 无 OpenCode package/binary/plugin/resource、无开发机绝对路径。
- 性能报告分离本地 overhead 与受控 provider-shaped first-event，不使用一次体验替代统计；可选真实外部 Provider 样本只能作为非阻断诊断。

### Verification

- 保存命令、版本、artifact、平台、样本数和结果摘要到 task evidence。
- macOS x64/arm64 分架构保存 workspace/staged/controlled packaged/loopback/metrics 与最终 artifact 实跑证据；不得只记录 waiver 或静态测试。
- 保存最终 packaged loopback/provider-shaped concurrency/abort 证据并明确 `realTurnVerified=false`；不得因缺少真实外部 Account/credential 把 release 标为 Blocked，也不得把 waiver 写成 Pass。
- 对允许的 `opencode` 搜索命中逐项解释。
- 更新 task record 的验证和未完成外部环境项；任何 release 阻断不得藏在 follow-up。

## PI-160 — Integration and release gate

### Objective

以 Integration Task 所有权完成最终 Spec/Standards 审阅、合并验证、canonical memory 提升和 release go/no-go；不让 feature branch 的自证替代集成事实。

### Dependencies

- `PI-150`。

### Owns

- Integration Task record、merge/rebase conflict handling。
- merge tree 的最终验证与独立 Spec/Standards review。
- accepted ADR、canonical current state/architecture/data flow/domain/success/evidence/commitments 清理。
- release decision、tag/runbook handoff；不自动 push/release，除非用户另行授权。

### Required work

1. 重新运行 Concurrent Task Gate，确认 main/worktree ownership 和最新 base。
2. 集成完整 feature tip，不选择性合并会留下双 runtime 的部分提交。
3. 在 merge tree 重跑风险相称的 focused/full/build/E2E/artifact/real smoke/perf checks。
4. 对照 `ML-CODE-PI-001` 逐条审阅，不以 ticket 自报 Done 代替证据。
5. 新增 accepted ADR：Pi 唯一 runtime、无 OpenCode fallback。
6. 更新 system overview/module map/data flow/business rules/success criteria/current state/README/evidence。
7. 关闭或改写仅对 OpenCode 有意义的 model-switch、dual-session、compaction、saturation commitments。
8. 执行零残留和 release note/rollback runbook 审阅。

### Acceptance

- 全部 Spec requirements 和 DoD 有可追踪证据，无未解释偏离。
- merge tree 与 feature tree 验证一致，无 main 回归。
- accepted ADR 和 canonical docs 描述实际 Pi 架构，不提前声称未跑的 macOS 或已豁免的真实外部 Provider 证据通过。
- accepted ADR、release note 与风险记录明确真实外部 Provider compatibility/concurrency/isolation 是用户接受的未验证风险，不声称 Pass；macOS x64/arm64 仍须有实际发布证据。
- OpenCode commitments 不再伪装为当前待办；需要保留的历史证据仍可追踪。
- 无 runtime fallback/compat layer/old route/dependency/artifact。
- release go/no-go 明确；若任一硬门不通过，状态保持 Blocked，不发布。

### Verification

- Integration Gate scripts、documentation drift gate。
- Final full command suite + artifact/real/runtime/performance evidence review。
- Independent human/reviewer Spec and Standards review；不要求特定智能体机制。

## 6. 票据状态模板

后续若同步为 task/issue，每张票据至少维护：

```text
Status: Pending | Ready | In progress | Blocked | Done
Depends on: <ticket ids>
Owner/worktree: <explicit owner>
Owned files/responsibility: <bounded scope>
Acceptance evidence: <tests, artifacts, measurements>
Contract changes: <none or linked upstream update>
Blockers: <concrete unmet condition>
```

禁止使用“代码基本完成”“看起来正常”“后续再测”作为 Done 证据。阻断项如果属于 Spec 硬门，必须留在当前 ticket，不得降级为 release 后 follow-up。