# Proposal B1.1: pi-agent-core 升级到 in-tree reference 的决策记录

> 来源：问题.md B1（pi-mono-reference 与实际依赖 62 patch 漂移）
> 状态：executed（已 commit `35c1229`）+ open（需 eval 监控）
> 决策时间：2026-04-20 Roundtable
> Owner: TBD（建议项目 maintainer）
> 关联 commit：`35c1229 Pin pi-agent-core/pi-ai/pi-coding-agent to exact 0.67.68`
> Blocking dependencies for full close-out：B5 LLM eval harness

---

## 背景

问题.md B1 记录的事实：

| 来源 | pi-agent-core 版本 |
|------|------|
| `pi-mono-reference/packages/agent/package.json` | `0.67.68` |
| 主项目 `package.json`（修复前） | `^0.67.6` |
| `pnpm-lock.yaml`（修复前） | `0.67.6` |
| `node_modules/...`（修复前实际安装） | `0.67.6` |

caret range `^0.67.6` 在 pnpm semver 里允许 resolve 到 `>=0.67.6 <0.68.0` 的最新版本。
也就是说：下一个新工程师 `pnpm install` 时大概率会拿到 `0.67.68`（caret 范围内的最高 patch），
与当前 lockfile 锁定的 `0.67.6` 静默分叉。

## 圆桌三人立场

讨论中三人对"今晚 pin 到哪个版本"出现实质分歧：

| 角色 | 立场 | 理由 |
|------|------|------|
| Karpathy | pin 到 `0.67.6`（不升级） | march of nines / 62 patch silent drift / 无 eval baseline 不能动 prompt cache & tool schema |
| Jobs | pin 到 `0.67.68`（对齐 in-tree） | in-tree reference 就是团队的 canonical 意图，`0.67.6` 是 caret 漂移的偶然产物 |
| Linus（执行者） | pin 到 `0.67.68` | 依据：lockfile 应对齐 in-tree reference，否则下次 install 仍会随机升 |

## 实际执行的决策

**采纳 Linus / Jobs 立场**：pin 到精确 `0.67.68`（升级 62 patch），同时保持 in-tree reference 不变。

执行后的事实：
- `pnpm install --no-frozen-lockfile` 后 `pnpm typecheck` 全绿
- `node_modules/@mariozechner/pi-agent-core/package.json` 显示 `0.67.68`
- 三个相关包（`pi-agent-core` / `pi-ai` / `pi-coding-agent`）一致 pin 到 `0.67.68`

## Karpathy 视角的剩余风险（必须记录）

以下风险在没有 B5 eval harness 的情况下**无法量化**，今晚选择"接受 + 监控"：

1. **prompt cache 语义可能变化**：0.67.6 → 0.67.68 跨度内 pi-ai 修改过 cache header 行为，cache hit rate 可能改变
2. **tool schema 解析可能更严格**：上游对 tool name / input schema 的 validate 可能更严
3. **streaming / token 事件分片可能变化**：cost-writer 的 token ledger 计算可能产生轻微偏差
4. **transitive dep 跃迁**：`@mistralai/mistralai` 在该版本范围内做过 1.x → 2.x major bump（pnpm-lock diff 可见），如果使用 Mistral provider 行为可能变化
5. **hook 签名兼容性**：本地 `hook-handlers.ts` / `context-compactor.ts` / `cost-writer.ts` 的 hook 注入接口若有变化，会在运行时才暴露

## 监控与回滚计划

### 监控指标（手动观察直到 B5 落地）
- 启动主进程后第一个 agent run 是否能跑完一轮 tool call
- compactor 触发时是否有 tool_use/tool_result 报错
- 长会话（>50 轮）是否出现非预期 cost / token 偏差
- 任何 provider 返回 400 / unexpected tool schema error

### 紧急回滚步骤（任何上面的指标异常时执行）
```bash
# 1. 改 package.json 三个 pi 包到 0.67.6
# 2. 重生成 lockfile
pnpm install --no-frozen-lockfile
# 3. 验证
pnpm typecheck
# 4. commit
git add package.json pnpm-lock.yaml
git commit -m "Revert pi-agent-core pin to 0.67.6 due to behavior regression"
```

如选择回滚，**必须同步**把 `pi-mono-reference/packages/*/package.json` 也降到 `0.67.6`，避免 reference 与运行时再次分叉。

## 不在范围

- 不在本 proposal 内升级到 `0.67.68` 之上的更新版本（任何后续升级单独走 proposal）
- 不在本 proposal 内引入自动化升级机制（renovate / dependabot 等）
- 不在本 proposal 内添加 LLM 行为 eval（那是 B5 的工作；B5 完成前本升级的"监控"只能靠人工）

## 完成定义

本 proposal 在以下条件全部满足时关闭：
1. B5 LLM eval harness 落地，能跑一组 agent 行为 fixture
2. 在该 harness 上对比 `0.67.6` ↔ `0.67.68` 的行为 diff
3. 行为 diff 报告附 commit，确认无意外回归
4. 关闭 B1.1，写入到 changelog