design/07-ai/done/7-34-acp-runtime-cleanup-availability-stability-tail-v1.md

# 7-34 [done] ACP runtime cleanup / availability / stability 尾项 checklist v1

> 创建时间：2026-05-21
>
> 当前状态：`DONE`
>
> 上位入口：`design/01-tree-first-graph-kernel/process/1-8-mvp-post-process-execution-order-v1.md`
>
> 来源：`design/07-ai/process/7-29-batch-i-ai-tool-final-content-acp-tail-closure-v1.md`

## 1. 目标

本清单承接 `7-29` 的 Batch I 结论，只处理 ACP runtime 与 Hermes tool contract 的尾项收口：

1. 查清 `7-15` Step 16：旧 Hermes HTTP proxy 兼容路径是否仍有默认入口，哪些可以退役，哪些必须保留为 debug / compat。
2. 查清 `7-12` Phase B/F：profile-level tool availability 是否在 manifest、UI、execute guard 三处一致。
3. 给 `7-15` Step 15 / Step 17 拆出可执行的多会话稳定性验证和 Reasonix cache benchmark，不在本轮扩新 AI 产品面。

本清单不解冻 Phase C Review Mode，不新增审阅 UI，不把 `mnote.doc.markdown_edit` 升回 local-first 普通 Markdown 默认主路径。

## 2. 当前已知事实

- `7-27` 已归档，`mnote.doc.markdown_edit` 在线写回已以最终 markdown 为真源。
- ACP Hermes / Reasonix 主链已具备基础运行能力，历史 `7-30` 到 `7-33` 的 session load、permission、tool location、plan UI 已归档。
- `hermes_client.rs` 中仍可能保留旧 HTTP proxy 兼容分支；是否仍被默认 runtime 触达需要本轮确认。
- `hermes_tools/manifest.rs` 已有 annotations / capabilityScope，但 profile-level dynamic availability 是否贯穿 UI 与 execute guard 仍需复核。

## 3. P0 Checklist

- [x] 旧 HTTP proxy 路径盘点完成：列出仍有调用者的 route / function / config，并标明 `default` / `compat` / `debug-only`。
- [x] 确认 `page_ai_workflow.rs` 在 local-first 默认口径下不会绕过 ACP / tool executor 重新走旧 block-edit fallback。
- [x] `7-15` 文档更新为“核心 ACP runtime 已完成，Step 15-17 拆到 7-34”，避免继续显示为整体未完成。
- [x] `7-12` Phase B/F 状态更新：已覆盖项、冻结项、待实现项分开写清楚。

## 4. P1 Checklist

- [x] profile-level tool availability 设计落点明确：manifest enabled、UI disabled/hidden、execute guard 三处的同源判断写清。
- [x] 多会话稳定性测试方案明确：至少覆盖 3 个并发 ACP session、cancel、子进程异常、事件去重。
- [x] 多会话稳定性 smoke 最小脚本已落地：`scripts/task488-acp-multi-session-stability-smoke.js`，覆盖 session/run/events/abort API 与 SSE terminal event 证据。
- [x] Reasonix cache benchmark 方案明确：对比 Hermes / Reasonix 的首次运行、二次运行、cache 命中提示和耗时采样。

## 5. P2 / 后续增强

- [ ] `7-27` 后续增强是否单独立项：`revisionRef` 注释可见性、复杂 GFM fallback、多余退役函数体删除。
- [ ] 若旧 HTTP proxy 不能立即删除，补 `debug/internal only` 标记和 route 文档。
- [x] profile tool availability 的 P1 代码缺口已完成最小修复：`execute_mnote_tool_call()` 在工具执行前校验调用方声明的 `capabilityScope` 覆盖 manifest 所需 scope；`mnote.page.get` 补齐只读 annotations。

## 6. Reasonix Worker 拆分

### Worker A：旧 HTTP proxy / fallback 调用链审查

Owner：

- `.codex/reasonix-tasks/results/batch-j-worker-a-http-proxy-fallback.md`

只读范围：

- `rust/crates/mnote-web/src/routes/hermes_client.rs`
- `rust/crates/mnote-web/src/page_ai_workflow.rs`
- `rust/crates/mnote-web/src/acp_runtime.rs`
- `rust/crates/mnote-web/src/acp_session_manager.rs`
- `rust/crates/mnote-web/src/routes/mod.rs`

要求：

- 不修改代码。
- 输出旧 HTTP proxy / page AI fallback 的真实调用链、默认入口、环境变量或 profile 开关。
- 分级为：必须退役 / compat 保留 / debug-only / 未被调用。

### Worker B：tool availability 三处一致性审查

Owner：

- `.codex/reasonix-tasks/results/batch-j-worker-b-tool-availability.md`

只读范围：

- `rust/crates/mnote-web/src/hermes_tools/manifest.rs`
- `rust/crates/mnote-web/src/hermes_tools/*.rs`
- `rust/crates/mnote-web/src/ssr/pages/layout.rs`
- `rust/crates/mnote-web/src/routes/hermes_tools.rs`

要求：

- 不修改代码。
- 审查 manifest / UI / execute guard 是否消费同一能力判断。
- 输出 P0 缺口和建议测试名，不直接实现。

### Worker C：ACP 稳定性与 benchmark checklist 草案

Owner：

- `.codex/reasonix-tasks/results/batch-j-worker-c-acp-stability-benchmark.md`

只读范围：

- `design/07-ai/done/7-15-page-ai-acp-agent-runtime-unified-layer-v1.md`
- `design/07-ai/done/7-25-acp-session-runtime-enhancement-plan-v1.md`
- `scripts/`
- `rust/crates/mnote-web/src/acp_*.rs`

要求：

- 不修改代码。
- 给出多会话稳定性 smoke / benchmark 的最小脚本方案、浏览器验证点、输出证据格式。
- 不要求立即实现压测脚本。

## 7. Codex 复核项

- [x] 等待 Worker A/B/C completion hook，单次最长 30 分钟，不短轮询。
- [x] 独立核查 Worker 结论涉及的关键调用链。
- [x] 更新本清单 P0/P1 状态。
- [x] 若出现 P0 代码缺口，拆下一轮实现 worker 或由 Codex 本地最小修复。
- [x] 跑 `git diff --check` 与相关 targeted tests。
- [x] 更新 `1-8` Batch E 状态。

## 8. 本轮执行记录

- 2026-05-21：Codex 创建 `7-34`，准备派发 Worker A/B/C 做只读审查与下一步测试方案拆分。
- 2026-05-21：Worker A/B/C 均通过 completion hook 回传。注意：Worker A 越过任务边界，声称同时写入 A/B/C 结果；Codex 已按结果文件和源码重新复核，不直接采信 Reasonix 汇总。
- 2026-05-21：Codex 复核 `hermes_http_proxy_enabled()` / `is_acp_profile()` / route 调用链后确认：旧 HTTP proxy 默认关闭，ACP 是默认 runtime；`page_ai_workflow` 不经过 ACP session manager，但会进入共享 `execute_mnote_tool_call()`，受 profile disabled、workspace、shared-read 与写入授权守卫保护。本轮无 P0 退役阻塞。
- 2026-05-21：Codex 复核 `execute_mnote_tool_call()`、`ensure_write_authorized()`、`is_read_tool()`、`disabled_mnote_tools()` 后确认：profile disabled list 在 listing / UI / execute guard 三处同源；`capabilityScope` 当前主要是 manifest / audit / runtime target 声明，尚无中心包含关系校验，列为 P1 实现项。
- 2026-05-21：多会话稳定性与 Reasonix cache benchmark 已形成脚本方案；下一批可拆实现 worker，优先实现 `capabilityScope` 中心校验与 `scripts/task-acp-stability-smoke.js`，cache benchmark 作为 P2 度量。
- 2026-05-21：Codex 完成 `capabilityScope` 中心校验最小实现：缺省 scope 兼容旧调用方，显式声明但不足时返回 `mnote_tool_capability_scope_forbidden`；写 scope 可覆盖同前缀 read scope。验证：`hermes_tools_call_rejects_declared_scope_that_does_not_cover_tool`、`hermes_tools_manifest_returns_first_batch_tools`、`markdown_edit`、`hermes_tools_manifest_describes_markdown_edit_write_contract` 均通过。
- 2026-05-21：Codex 新增 `scripts/task488-acp-multi-session-stability-smoke.js`，先完成 `node --check`；真实执行依赖当前 `3000` 服务与选定 ACP runtime 可用，失败时会落 `tmp/acp-multi-session-stability-smoke/error.json`，成功时落 `result.json` 与每个 run 的事件 JSON。
- 2026-05-21：Codex 修复 `task488` smoke 的 SSE 读取策略：从 Playwright `context.request.fetch` 改为 Node 原生 `fetch` + 登录 cookie，读取到 `run.completed` / `run.failed` / `run.aborted` terminal event 后主动关闭流，避免 Playwright context 关闭造成假失败。
- 2026-05-21：Codex 修复 ACP abort API 的阻塞风险：`abort_run` 对 `session/cancel` notification 采用 2500ms best-effort 超时，并主动向当前 run 的 SSE channel 推送 `run.aborted`；后续 prompt 结束时若 runtime 已 abort，不会再覆盖为 completed。
- 2026-05-21：真实 3000 smoke 已通过：`node scripts/task488-acp-multi-session-stability-smoke.js` 创建 3 个 `reasonix` ACP session / run，取消第 2 个 run，最终事件为 `run.completed`、`run.aborted`、`run.completed`；证据写入 `tmp/acp-multi-session-stability-smoke/result.json` 和 `events-*.json`。

## 9. 归档说明

本清单 P0/P1 已完成并有代码与 smoke 证据，归档到 `design/07-ai/done/`。

仍保留为后续增强的事项：

- `7-27` 的 `revisionRef` 注释可见性、复杂 GFM fallback、多余退役函数体删除。
- 旧 Hermes HTTP proxy 的更细 debug/internal only 文档标记。
- Reasonix cache benchmark 的长期耗时采样；当前只冻结方案，不作为 1-8 Batch E 阻塞项。
-											advance 1-8 post-mvp execution batches
										
										
											2026-05-21 23:53:39 +08:00
+								# 7-34 [done] ACP runtime cleanup / availability / stability 尾项 checklist v1
 								> 创建时间：2026-05-21
 								>
 								> 当前状态：`DONE`
 								>
 								> 上位入口：`design/01-tree-first-graph-kernel/process/1-8-mvp-post-process-execution-order-v1.md`
 								>
 								> 来源：`design/07-ai/process/7-29-batch-i-ai-tool-final-content-acp-tail-closure-v1.md`
 								## 1. 目标
 								本清单承接 `7-29` 的 Batch I 结论，只处理 ACP runtime 与 Hermes tool contract 的尾项收口：
 . 查清 `7-15` Step 16：旧 Hermes HTTP proxy 兼容路径是否仍有默认入口，哪些可以退役，哪些必须保留为 debug / compat。
 . 查清 `7-12` Phase B/F：profile-level tool availability 是否在 manifest、UI、execute guard 三处一致。
 . 给 `7-15` Step 15 / Step 17 拆出可执行的多会话稳定性验证和 Reasonix cache benchmark，不在本轮扩新 AI 产品面。
 								本清单不解冻 Phase C Review Mode，不新增审阅 UI，不把 `mnote.doc.markdown_edit` 升回 local-first 普通 Markdown 默认主路径。
 								## 2. 当前已知事实
 								- `7-27` 已归档，`mnote.doc.markdown_edit` 在线写回已以最终 markdown 为真源。
 								- ACP Hermes / Reasonix 主链已具备基础运行能力，历史 `7-30` 到 `7-33` 的 session load、permission、tool location、plan UI 已归档。
 								- `hermes_client.rs` 中仍可能保留旧 HTTP proxy 兼容分支；是否仍被默认 runtime 触达需要本轮确认。
 								- `hermes_tools/manifest.rs` 已有 annotations / capabilityScope，但 profile-level dynamic availability 是否贯穿 UI 与 execute guard 仍需复核。
 								## 3. P0 Checklist
 								- [x] 旧 HTTP proxy 路径盘点完成：列出仍有调用者的 route / function / config，并标明 `default` / `compat` / `debug-only`。
 								- [x] 确认 `page_ai_workflow.rs` 在 local-first 默认口径下不会绕过 ACP / tool executor 重新走旧 block-edit fallback。
 								- [x] `7-15` 文档更新为“核心 ACP runtime 已完成，Step 15-17 拆到 7-34”，避免继续显示为整体未完成。
 								- [x] `7-12` Phase B/F 状态更新：已覆盖项、冻结项、待实现项分开写清楚。
 								## 4. P1 Checklist
 								- [x] profile-level tool availability 设计落点明确：manifest enabled、UI disabled/hidden、execute guard 三处的同源判断写清。
 								- [x] 多会话稳定性测试方案明确：至少覆盖 3 个并发 ACP session、cancel、子进程异常、事件去重。
 								- [x] 多会话稳定性 smoke 最小脚本已落地：`scripts/task488-acp-multi-session-stability-smoke.js`，覆盖 session/run/events/abort API 与 SSE terminal event 证据。
 								- [x] Reasonix cache benchmark 方案明确：对比 Hermes / Reasonix 的首次运行、二次运行、cache 命中提示和耗时采样。
 								## 5. P2 / 后续增强
 								- [ ] `7-27` 后续增强是否单独立项：`revisionRef` 注释可见性、复杂 GFM fallback、多余退役函数体删除。
 								- [ ] 若旧 HTTP proxy 不能立即删除，补 `debug/internal only` 标记和 route 文档。
 								- [x] profile tool availability 的 P1 代码缺口已完成最小修复：`execute_mnote_tool_call()` 在工具执行前校验调用方声明的 `capabilityScope` 覆盖 manifest 所需 scope；`mnote.page.get` 补齐只读 annotations。
 								## 6. Reasonix Worker 拆分
 								### Worker A：旧 HTTP proxy / fallback 调用链审查
 								Owner：
 								- `.codex/reasonix-tasks/results/batch-j-worker-a-http-proxy-fallback.md`
 								只读范围：
 								- `rust/crates/mnote-web/src/routes/hermes_client.rs`
 								- `rust/crates/mnote-web/src/page_ai_workflow.rs`
 								- `rust/crates/mnote-web/src/acp_runtime.rs`
 								- `rust/crates/mnote-web/src/acp_session_manager.rs`
 								- `rust/crates/mnote-web/src/routes/mod.rs`
 								要求：
 								- 不修改代码。
 								- 输出旧 HTTP proxy / page AI fallback 的真实调用链、默认入口、环境变量或 profile 开关。
 								- 分级为：必须退役 / compat 保留 / debug-only / 未被调用。
 								### Worker B：tool availability 三处一致性审查
 								Owner：
 								- `.codex/reasonix-tasks/results/batch-j-worker-b-tool-availability.md`
 								只读范围：
 								- `rust/crates/mnote-web/src/hermes_tools/manifest.rs`
 								- `rust/crates/mnote-web/src/hermes_tools/*.rs`
 								- `rust/crates/mnote-web/src/ssr/pages/layout.rs`
 								- `rust/crates/mnote-web/src/routes/hermes_tools.rs`
 								要求：
 								- 不修改代码。
 								- 审查 manifest / UI / execute guard 是否消费同一能力判断。
 								- 输出 P0 缺口和建议测试名，不直接实现。
 								### Worker C：ACP 稳定性与 benchmark checklist 草案
 								Owner：
 								- `.codex/reasonix-tasks/results/batch-j-worker-c-acp-stability-benchmark.md`
 								只读范围：
-											chore: align local-first control plane and editor fixes
										
										
											2026-05-23 23:38:42 +08:00
+								- `design/07-ai/done/7-15-page-ai-acp-agent-runtime-unified-layer-v1.md`
-											advance 1-8 post-mvp execution batches
										
										
											2026-05-21 23:53:39 +08:00
+								- `design/07-ai/done/7-25-acp-session-runtime-enhancement-plan-v1.md`
 								- `scripts/`
 								- `rust/crates/mnote-web/src/acp_*.rs`
 								要求：
 								- 不修改代码。
 								- 给出多会话稳定性 smoke / benchmark 的最小脚本方案、浏览器验证点、输出证据格式。
 								- 不要求立即实现压测脚本。
 								## 7. Codex 复核项
 								- [x] 等待 Worker A/B/C completion hook，单次最长 30 分钟，不短轮询。
 								- [x] 独立核查 Worker 结论涉及的关键调用链。
 								- [x] 更新本清单 P0/P1 状态。
 								- [x] 若出现 P0 代码缺口，拆下一轮实现 worker 或由 Codex 本地最小修复。
 								- [x] 跑 `git diff --check` 与相关 targeted tests。
 								- [x] 更新 `1-8` Batch E 状态。
 								## 8. 本轮执行记录
 								- 2026-05-21：Codex 创建 `7-34`，准备派发 Worker A/B/C 做只读审查与下一步测试方案拆分。
 								- 2026-05-21：Worker A/B/C 均通过 completion hook 回传。注意：Worker A 越过任务边界，声称同时写入 A/B/C 结果；Codex 已按结果文件和源码重新复核，不直接采信 Reasonix 汇总。
 								- 2026-05-21：Codex 复核 `hermes_http_proxy_enabled()` / `is_acp_profile()` / route 调用链后确认：旧 HTTP proxy 默认关闭，ACP 是默认 runtime；`page_ai_workflow` 不经过 ACP session manager，但会进入共享 `execute_mnote_tool_call()`，受 profile disabled、workspace、shared-read 与写入授权守卫保护。本轮无 P0 退役阻塞。
 								- 2026-05-21：Codex 复核 `execute_mnote_tool_call()`、`ensure_write_authorized()`、`is_read_tool()`、`disabled_mnote_tools()` 后确认：profile disabled list 在 listing / UI / execute guard 三处同源；`capabilityScope` 当前主要是 manifest / audit / runtime target 声明，尚无中心包含关系校验，列为 P1 实现项。
 								- 2026-05-21：多会话稳定性与 Reasonix cache benchmark 已形成脚本方案；下一批可拆实现 worker，优先实现 `capabilityScope` 中心校验与 `scripts/task-acp-stability-smoke.js`，cache benchmark 作为 P2 度量。
 								- 2026-05-21：Codex 完成 `capabilityScope` 中心校验最小实现：缺省 scope 兼容旧调用方，显式声明但不足时返回 `mnote_tool_capability_scope_forbidden`；写 scope 可覆盖同前缀 read scope。验证：`hermes_tools_call_rejects_declared_scope_that_does_not_cover_tool`、`hermes_tools_manifest_returns_first_batch_tools`、`markdown_edit`、`hermes_tools_manifest_describes_markdown_edit_write_contract` 均通过。
 								- 2026-05-21：Codex 新增 `scripts/task488-acp-multi-session-stability-smoke.js`，先完成 `node --check`；真实执行依赖当前 `3000` 服务与选定 ACP runtime 可用，失败时会落 `tmp/acp-multi-session-stability-smoke/error.json`，成功时落 `result.json` 与每个 run 的事件 JSON。
 								- 2026-05-21：Codex 修复 `task488` smoke 的 SSE 读取策略：从 Playwright `context.request.fetch` 改为 Node 原生 `fetch` + 登录 cookie，读取到 `run.completed` / `run.failed` / `run.aborted` terminal event 后主动关闭流，避免 Playwright context 关闭造成假失败。
 								- 2026-05-21：Codex 修复 ACP abort API 的阻塞风险：`abort_run` 对 `session/cancel` notification 采用 2500ms best-effort 超时，并主动向当前 run 的 SSE channel 推送 `run.aborted`；后续 prompt 结束时若 runtime 已 abort，不会再覆盖为 completed。
 								- 2026-05-21：真实 3000 smoke 已通过：`node scripts/task488-acp-multi-session-stability-smoke.js` 创建 3 个 `reasonix` ACP session / run，取消第 2 个 run，最终事件为 `run.completed`、`run.aborted`、`run.completed`；证据写入 `tmp/acp-multi-session-stability-smoke/result.json` 和 `events-*.json`。
 								## 9. 归档说明
 								本清单 P0/P1 已完成并有代码与 smoke 证据，归档到 `design/07-ai/done/`。
 								仍保留为后续增强的事项：
 								- `7-27` 的 `revisionRef` 注释可见性、复杂 GFM fallback、多余退役函数体删除。
 								- 旧 Hermes HTTP proxy 的更细 debug/internal only 文档标记。
 								- Reasonix cache benchmark 的长期耗时采样；当前只冻结方案，不作为 1-8 Batch E 阻塞项。