codex-app-server/docs/chv-muse-p1-gap.md

# 对齐 Muse P1 差距表：常驻 VM + WarmPool + 气球 + vsock

依据：`~/workspace/research_notes/meta-muse-ai-architecture-20261101-0755/report.md`
（官方以 Meta security.muse.ai 2026-09-08 为准；第三方拆解只作参考，
逆向细节不得写成官方架构）。Muse 模型一句话：每用户一台常驻 Secure VM，
闲置靠气球压内存，宿主–客机走 vsock 通知通道。

本轨范围只限 P1：常驻 VM、WarmPool 扶正、内存气球、vsock 通道。
不碰 P2（客机 nspawn 单元、浏览器子代理独立）、不碰 P3（authd 替身凭证、
Sentinel 式出口审批）。分支 `feat-chv-muse-p1`（从 `feat-chv-cover100`
分出，基线 HEAD `06c3e17`）。

## 1. 现状 vs Muse

| 项 | 现状（实测/代码为准） | Muse 目标 | 本轨做法 |
|---|---|---|---|
| VM 生命周期 | 1 任务 = 1 VM，用完销毁；冷启动到 SSH 实测 11 秒 | 每用户一台常驻 Secure VM（hatchling），任务来了直接用 | 新增常驻服务：每用户一台常驻 VM（暂停态），任务到时 resume；池空回落冷启动（11 秒路径不动） |
| 派发查池 | `_run_with_vm` 绝不查池，`warm_pool_wired_to_dispatch` 恒 False；worker 派发前查池未接线 | 常驻 VM 就是派发目标，无冷启动 | `_run_with_vm` 接常驻路径：先 acquire 常驻 VM（resume + 等 SSH 就绪），无可用时回落 `wake_vm` |
| 预热池状态 | `experimental_pool.WarmPool` 纯实验，生产禁 import（ADR-12）；ADR-5 定案：预热盘是干净快照盘、不是任务盘，接线须先实现任务盘重供给 | —（Muse 无此概念：常驻 VM 的盘就是用户工作区盘） | WarmPool 实验模块不动（仍禁生产 import）；新建生产模块 `resident_pool.py`。常驻 VM 的盘是**每用户持久工作区盘**，不是每任务新盘 |
| 内存 | 固定 2G，无气球 | 气球 + 空闲页上报，闲置 8G 压到约 2G 工作集 | CHV 配置加 virtio-balloon + free-page-reporting（默认开，可关） |
| 宿主–客机通道 | 只 SSH；executor 文档明确“只选 SSH，不做 vsock 第二套”（旧决策） | vsock 通知通道（另有 Unix socket + SO_PEERCRED 的单元内 IPC，属 P2/P3 层） | vsock 只做最小 notify（就绪/心跳上报），与 SSH 并存；SSH 仍是命令通道与就绪判定，host key 钉死不动 |
| 池持久化/孤儿 | WarmPool registry `state_dir/warm-pool.json` 已有（原子写、损坏 quarantine、重启后条目一律 orphan 不复用） | — | 常驻池复用同款 registry 语义，另建 `resident-pool.json`；worker 启动/关闭走 `orphans` facade 清理，不自动复用上一世条目 |

## 2. 改了什么（本轨交付物）

- `cloud/chv/resident_pool.py`（新）：常驻池。状态机 cold → provisioning →
  paused → running → paused；`acquire(user)` resume + SSH 就绪，
  `release(user)` pause 不销毁；空闲回收策略（pause 后常驻，超闲置阈值
  关机+快照，阈值可配，默认不开自动关机）；registry 原子落盘、损坏
  quarantine、重启后不复用。
- `cloud/chv/executor.py`：`_run_with_vm` 接常驻路径（默认开，可配关；
  常驻失败一律回落冷启动，绝不因池坏而丢任务）；`_create` payload 加
  balloon/vsock 设备。
- `cloud/chv/config.py`：`CHV_RESIDENT_IDLE_MINUTES`、`CHV_BALLOON`、
  `CHV_VSOCK`（开关 + CID），非法值 ValueError，不静默 fallback。
- `cloud/chv/worker_adapter.py`：常驻池 reconcile facade（接 `orphans`）。
- `cloud/chv/vsock.py`（新，宿主侧）：vsock notify 客户端/监听最小实现。
- `cloud/chv/guest/vsock_notify.py`（新，客内脚本）：连宿主 CID 2 发
  ready/心跳。**只写脚本文件，不改 `chv-guest/build.sh`**——镜像集成
  是 P2 的范围，本轨只留接入说明。
- `cloud/tests/test_chv_muse_p1_*.py`（新）：常驻池、气球/vsock 配置与
  payload、回落语义的单测；全量 cloud 套件全过。
- `docs/chv-architecture.md`：ADR-5/ADR-12 补充新决策（常驻路径取代
  WarmPool 接线问题），旧定案不删、只追加。

## 3. 诚实边界（本轮不宣称的东西）

1. **隔离单元变了**：常驻路径下隔离单元从“每任务”变成“每用户”——同一
   用户的任务共享同一台常驻 VM 与同一块工作区盘，每任务新盘的不变量在
   常驻路径上不再成立。冷启动路径（每任务新盘）保留作回落与隔离严格场景。
   当前是单租户，这个取舍可接受；多租户重审前不得把常驻路径当多租户隔离。
2. **性能数字全是待验证目标，不是结果**：resume 1–2 秒、到 SSH 5 秒内、
   气球压内存——本轮无真机验证（第三棒 V-1～V-9 占着 WSL 测试机），一律
   记入“真机待验证清单”，不在代码/文档里写成已测得。
3. **气球 API 形态须核对**：CHV 54 的 balloon/vsock payload 字段以
   Cloud Hypervisor 官方文档/二进制为准；本机无 /dev/kvm，无法本地起
   VM 校验，只做配置层 + payload 单测。
4. **vsock 端到端未通**：本轮只做到宿主侧 + 客内脚本；客内脚本进镜像、
   真机收发验证都待 P2 集成后、测试机空闲时再做。SSH 不动，vsock 坏了
   不影响任务。
5. **WarmPool 实验模块不动**：不把它翻成生产模块，不改
   `wired_to_dispatch`；常驻是新模块、新路径，旧实验代码与测试原样保留。

## 4. 恢复收尾（分离后在本分支修掉的回归）

分离时 chv 子集 3 失败 + 1 错误，全量另有 2 失败，均已修
掉、未删测试、未改断言：

- **VmDeathTest 两处**：根因不是生产判定错——探针实证，
  常驻 VM 真死时 `_run_on_resident` 两态都正确判
  interrupted；错的是旧测试的死亡模拟：它杀
  `ex._vms["chv-abc123"]`，P1 常驻路由下该 VM 从未 wake、
  登记里只有 `chv-resident-default`，模拟是空操作。修
  法：模拟器改杀 dispatch 时已登记的 VM（即实际跑命令
  的那台），断言不动。
- **test_cloud_hypervisor 两处冷路径测试**
  （`test_dispatch_wakes_runs_shuts_down`、
  `test_dispatch_missing_dependency_does_not_call_runner`）：
  P1 把常驻改成默认开后，它们测的冷启动序列不再是默认
  路径；修法：两测试显式 `CHV_RESIDENT_ENABLED=0`，
  继续钉冷启动行为，断言不动。常驻 dispatch 由 P1 新测
  试覆盖。附带说明：建池 wake 失败后的清理 shutdown 是
  既定行为（P1 回落测试钉住），不是回归。
- **超 50 行**：`_balloon_vsock_payload`（54）拆出
  `_resolve_vsock_socket`；`vsock.listen_notify`（55）
  拆出 `_bind_notify_listener`；行为不动。
- **mypy**：`resident_pool.py:208` 加 None 守卫后干净；
  `executor.py` 的 `out` 未注解错与 `marker_tools.py:142`
  是基线 06c3e17 已有（`git show` 核对，P1 diff 零行碰
  `out`），如实记录、未动。