@jun133/athlete 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jun133/athlete",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "A global terminal AI coding assistant.",
   "keywords": [
     "athlete",
@@ -50,13 +50,16 @@
     "cfb": "^1.2.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.1",
+    "cors": "^2.8.6",
     "diff": "^8.0.2",
     "docx": "^9.5.1",
     "dompurify": "^3.3.3",
     "dotenv": "^17.2.3",
     "env-paths": "^3.0.0",
     "execa": "^9.6.0",
+    "express": "^5.2.1",
     "fast-glob": "^3.3.3",
+    "lowdb": "^7.0.1",
     "mammoth": "^1.10.0",
     "marked": "^17.0.4",
     "openai": "^6.4.0",

package/scripts/postinstall-playwright.mjs

@@ -34,20 +34,20 @@ if ((result.status ?? 1) !== 0) {
   console.warn(message);
 }
 
-function resolveInstallTarget(rawValue) {
-  switch (String(rawValue ?? "").trim().toLowerCase()) {
-    case "chrome":
-      return "chrome";
+function resolveInstallTarget(rawValue) {
+  switch (String(rawValue ?? "").trim().toLowerCase()) {
+    case "chrome":
+      return "chrome";
     case "firefox":
       return "firefox";
     case "webkit":
       return "webkit";
-    case "msedge":
-      return "msedge";
-    default:
-      return "chrome";
-  }
-}
+    case "msedge":
+      return "msedge";
+    default:
+      return "chromium";
+  }
+}
 
 function resolvePlaywrightCliPath() {
   const packageJsonPath = require.resolve("playwright/package.json");

package/spec/architecture//346/200/273/344/275/223/346/236/266/346/236/204.md

@@ -28,12 +28,13 @@ Athlete 是一个终端里的智能体运行系统：
 
 目录：`src/tools/` `src/mcp/`
 
-负责：
-
-- 向模型暴露动作
-- 参数解析
-- 机器约束检查
-- 调用底层能力
+负责：
+
+- 向模型暴露动作
+- 参数解析
+- 机器约束检查
+- 调用底层能力
+- 统一治理 metadata、fail-closed 暴露过滤、routing hint 与 signal 校验
 
 ### 3. Skill Plane
 
@@ -70,18 +71,19 @@ Athlete 是一个终端里的智能体运行系统：
 - worktree 目录
 - MCP 浏览器
 
-### 6. Orchestrator Layer
-
-目录：`src/orchestrator/`
-
-负责：
-
-- 复杂度判断
-- 最小任务图落盘
-- self / subagent / teammate / background 路由
-- lead slice 开始前的任务组织
-
-## 当前最重要的架构边界
+### 6. Orchestrator Layer
+
+目录：`src/orchestrator/`
+
+负责：
+
+- 复杂度判断
+- 最小任务图落盘
+- 从 task / team / background / worktree 真相源派生任务 lifecycle
+- self / subagent / teammate / background 路由
+- lead slice 开始前的任务组织
+
+## 当前最重要的架构边界
 
 ### 控制面
 
@@ -106,6 +108,8 @@ Athlete 是一个终端里的智能体运行系统：
 
 1. 控制面不直接改文件。
 2. 执行面不发明控制面真相。
-3. orchestrator 负责调度，不负责具体文件改写。
-4. tools 提供动作，skills 提供 workflow，二者不互相替代。
-5. 主循环只做调度；closeout、verification signal、workflow gating 这类长期规则要下沉到独立模块。
+3. orchestrator 负责调度，不负责具体文件改写。
+4. tools 提供动作，skills 提供 workflow，二者不互相替代。
+5. 主循环只做调度；closeout、verification signal、workflow gating 这类长期规则要下沉到独立模块。
+6. tool priority、browser-first、document routing、MCP fail-closed 之类策略属于机器层，不属于 prompt 路由表。
+7. task readiness、ownership、handoff legality、worktree binding reality 由机器从既有真相源派生，不靠 prompt 记忆。

package/spec/architecture//347/212/266/346/200/201/344/270/216/347/234/237/347/233/270/346/272/220.md

@@ -8,17 +8,18 @@ Athlete 要跑长任务、协作任务和恢复任务，关键状态不能只放
 
 ## 当前真相源
 
-### TaskStore
-
-回答：
-
-- 有哪些任务
-- 哪些任务被阻塞
-- 谁被指派
-- 谁正在做
-- 任务绑定了哪个 worktree
-
-状态目录：`.athlete/tasks/`
+### TaskStore
+
+回答：
+
+- 有哪些任务
+- 哪些任务被阻塞
+- 谁被指派
+- 谁正在做
+- 任务绑定了哪个 worktree
+- orchestrator task 的 objective / kind / handoff metadata 是什么
+
+状态目录：`.athlete/tasks/`
 
 ### TeamStore
 
@@ -109,9 +110,11 @@ Athlete 要跑长任务、协作任务和恢复任务，关键状态不能只放
 - 有 request / response 对应关系
 - 有持久化状态
 
-## 当前规则
-
-1. 新增状态前，先问是不是已有真相源应扩字段。
-2. 能复用现有真相源，就不要新造平行 JSON 文件。
-3. 任何需要跨 turn、跨 agent 保持一致的信息，都不能只存在 system prompt 里。
-4. 普通消息不能代替正式审批。
+## 当前规则
+
+1. 新增状态前，先问是不是已有真相源应扩字段。
+2. 能复用现有真相源，就不要新造平行 JSON 文件。
+3. 任何需要跨 turn、跨 agent 保持一致的信息，都不能只存在 system prompt 里。
+4. 普通消息不能代替正式审批。
+5. task lifecycle 不是单独落盘的新 JSON；它由 `TaskStore` + `TeamStore` + `BackgroundJobStore` + `WorktreeStore` 的现有事实派生。
+6. handoff 缺失或冲突时必须 fail-closed，例如：缺失 teammate、缺失 background job、失效 worktree 绑定。

package/spec/architecture//350/277/220/350/241/214/346/227/266/345/276/252/347/216/257.md

@@ -7,76 +7,133 @@
 1. 组装 system prompt
 2. 注入运行时状态
 3. 调模型
-4. 执行工具
-5. 判断继续、yield、暂停、结束
-
-当前 lead 路径接法：
-
-- `runManagedAgentTurn`
-- `prepareLeadTurn`
-- `runAgentTurn`
-
-也就是说：
-
-- orchestrator 在 lead slice 开始前先做任务组织与派工
-- `runTurn` 继续专注模型请求、工具执行、continuation、verification、compact
-- teammate / subagent loop 不走 lead orchestrator
+4. 执行工具
+5. 判断继续、yield、暂停、结束
+
+当前 lead 路径接法：
+
+- `runManagedAgentTurn`
+- `prepareLeadTurn`
+- `runAgentTurn`
+
+也就是说：
+
+- orchestrator 在 lead slice 开始前先做任务组织与派工
+- 派工前先从 task / team / background / worktree 真相源派生任务 lifecycle
+- `runTurn` 继续专注模型请求、工具执行、continuation、verification、compact
+- teammate / subagent loop 不走 lead orchestrator
+
+当前 one-shot CLI 也走同一套 machine truth，只是终端外壳不同：
+
+- `src/cli.ts`
+- `src/cli/support.ts`
+
+one-shot 结束时必须把 terminal transition / verification / acceptance 收敛成稳定 closeout contract 输出。
+
+交互式 CLI 退出时还有一条独立规则：
+
+- 如果当前项目没有运行中的后台进程，`quit` 直接退出
+- 如果有运行中的后台进程，必须先列出它们，再由用户二选一：
+  - kill 全部后台进程并退出
+  - 取消退出继续运行
+- kill 不彻底时必须 fail-closed，不允许带着不可见孤儿进程假装退出成功
 
 ## 当前最重要的机器规则
 
-### 计划规则
-
-变更型动作默认要求先 `todo_write`。
+### 计划规则
+
+变更型动作默认要求先 `todo_write`。
+
+### 任务编排规则
+
+lead 编排不再只看 task status 字段，而是看机器派生的 lifecycle：
+
+- `blocked`
+- `ready`
+- `active`
+- `completed`
+
+并同时判断：
+
+- runnableBy 是 lead / teammate / nobody
+- handoff 是否有合法控制面事实支撑
+- worktree 绑定是否仍然有效
+
+如果 teammate / background / worktree 的事实缺失或冲突，lead 路径会阻断新的派工，而不是继续默许推进。
 
 ### inbox 规则
 
 lead 和 teammate 的 inbox 在 turn 开头统一注入。
 
-### verification 规则
+### verification 规则
 
 发生文件改动或 mutating shell 后，会进入 verification 状态机。
 
 verification 不是无限提醒：
 
-- `pendingPaths` 会随 session 持久化，continuation 后仍然有效
-- 显式 build / test / verify 命令会记录为正式 verification attempt
-- 对轻量交付物（如 `validation/*.md`、`.txt`）的定向 `read_file` 检查，也会被记录为一次通过的轻量验证
-- 如果任务已经结束、输出文件已经存在且属于轻量交付物，finalize 会先尝试 auto-readback，再决定是否 pause 给用户
-
-### 收口规则
-
-当主目标已经满足时，runtime 会优先结束，而不是继续补做 task / todo / verification 文书动作。
-
-- 收口判断不只看模型文本，还看 `changedPaths`、`verificationState`、todo 完成度与本轮是否已有实质工具活动
+- `pendingPaths` 会随 session 持久化，continuation 后仍然有效
+- 显式 build / test / verify 命令会记录为正式 verification attempt
+- 对轻量交付物（如 `validation/*.md`、`.txt`）的定向 `read_file` 检查，也会被记录为一次通过的轻量验证
+- 如果任务已经结束、输出文件已经存在且属于轻量交付物，finalize 会先尝试 auto-readback，再决定是否 pause 给用户
+- acceptance / verification 的跨生态判断统一经过 signal 层，不直接匹配某个 adapter 工具名
+
+### 收口规则
+
+当主目标已经满足时，runtime 会优先结束，而不是继续补做 task / todo / verification 文书动作。
+
+- 收口判断不只看模型文本，还看 `changedPaths`、`verificationState`、todo 完成度与本轮是否已有实质工具活动
 - 一旦进入“应该收口”的区间，`task_list` / `task_get` / `task_update` 会在工具集里被隐藏
 - 当 todo 已全部完成时，`todo_write` 也会在收口阶段从工具集中移除，避免重复 closeout
 - 旧 todo 过时但真实工作已完成时，不再把 stale todo 当成 finalize 的硬阻塞
 
-### continuation 规则
-
-工具步数过多时，不中断任务，而是自动续跑。
-
-### compact 规则
+### continuation 规则
+
+工具步数过多时，不中断任务，而是自动续跑。
+
+### runtime transition 规则
+
+continue / recover / yield / pause / finalize 不再只靠零散布尔值和字符串拼接。
+
+- runtime 会产出结构化 transition：`action + reason code + detail`
+- `checkpoint.flow.lastTransition` 持久化最近一次关键 runtime 决策
+- `checkpoint.flow.reason` 只是从结构化 transition 派生的紧凑视图，不再是独立真相源
+- continuation / resume / recovery / closeout 都应优先读取这一层机器状态，而不是反推 prompt 文案
+
+### compact 规则
 
 上下文过长时，自动压缩请求上下文，不直接放弃任务。
 
-### 浏览器 workflow 规则
-
-在相关 skill 已加载且浏览器工具可用时：
-
-- 自然语言网页任务优先走 Playwright MCP 工具
-- shell 网页抓取只能作为 fallback
-- 在导航和 snapshot 之前，shell detour 会被 workflow guard 拦住
-
-### 交互等待反馈
+### 浏览器 workflow 规则
+
+在相关 skill 已加载且浏览器工具可用时：
+
+- 自然语言网页任务优先走 browser capability 工具
+- shell 网页抓取只能作为 fallback
+- 在导航和 snapshot 之前，shell detour 会被 workflow guard 拦住
+
+这里的“浏览器工具”可以由 Playwright MCP 提供，也可以由别的 adapter 提供；上层规则只认 browser capability / browser step。
+
+### 文档 workflow 规则
+
+当 file introspection 或 tool recovery 指向专用文档能力时：
+
+- 上层优先走 `document.read` / `spreadsheet.read` capability
+- 文档 phase 推进只认 `document_read_completed` signal
+- 不把 MinerU 名字继续塞进 acceptance / phase / route-change 主体
+
+### 交互等待反馈
 
 交互模式下，用户发出输入后、模型真正开始输出前，会显示短暂 spinner。
 
 它属于 UI 层，不参与 agent 状态机本身。
 
-## 设计要求
-
-1. loop 只保留全局调度规则。
-2. 具体模块细节下沉到各自目录。
-3. 新增长期能力时，优先接到 runtime state、tool priority 或 workflow guard，而不是直接堆 prompt。
-4. “应该结束”的判断必须落在机器层，不能只靠 prompt 提醒模型自觉收口。
+## 设计要求
+
+1. loop 只保留全局调度规则。
+2. 具体模块细节下沉到各自目录。
+3. static system prompt 只承载高层 operating contract，不重复 machine-enforced 的 workflow / verification / closeout 细则。
+4. 新增长期能力时，优先接到 runtime state、tool priority 或 workflow guard，而不是直接堆 prompt。
+5. “应该结束”的判断必须落在机器层，不能只靠 prompt 提醒模型自觉收口。
+6. runtime 的关键转移原因必须可持久化、可测试、可区分，不能只留在 status 文本里。
+7. lead orchestrator 只消费 task lifecycle 这种派生控制面事实，不新增平行 orchestration 真相源。
+8. provider / browser / document 的生态差异可以停留在 adapter 层，但不能上浮成主循环规则。

package/spec/implementation//347/233/256/345/275/225/347/273/223/346/236/204/345/210/260/344/273/243/347/240/201/346/226/207/344/273/266/346/230/240/345/260/204/350/241/250.md

@@ -1,60 +1,101 @@
 # 目录结构到代码文件映射表
 
-## 当前主要目录
-
-- `src/agent/`: 主循环、prompt、continuation、verification、closeout
-- `src/agent/checkpoint/`: checkpoint 归一化、推导、resume 输入、prompt block
-- `src/agent/runtimeMetrics/`: runtime metrics 累积与 runtime summary
-- `src/tools/`: 模型可见工具与 handler
-- `src/skills/`: skill schema、discovery、matching、loading、workflow guard
+## 当前主要目录
+
+- `src/agent/`: 主循环与稳定 façade
+- `src/agent/provider.ts`: provider capability profile、request body 组装、provider fallback / recovery model 选择
+- `src/agent/checkpoint/`: checkpoint 归一化、推导、resume 输入、prompt block
+- `src/agent/context/`: request context 组装与压缩
+- `src/agent/session/`: session message / todo / task state / session store 真相整理
+- `src/agent/toolResults/`: tool result preview、transport 压缩、externalize 落盘
+- `src/agent/turn/`: managed turn、closeout、finalize、tool execution、loop / recovery 辅助
+- `src/agent/verification/`: verification state 与 lightweight / auto-readback signals
+- `src/agent/acceptance/signals.ts`: acceptance signal 归一化
+- `src/agent/runtimeMetrics/`: runtime metrics 累积与 runtime summary
+- `src/tools/`: 模型可见工具与 handler
+- `src/tools/governance.ts`: 工具治理 metadata、fail-closed 默认、result signal 校验
+- `src/tools/routing.ts`: 文档 / spreadsheet 专用工具路由 hint
+- `src/skills/`: skill schema、discovery、matching、loading、workflow guard
 - `src/mcp/`: MCP 总接入层
 - `src/mcp/playwright/`: Playwright MCP 配置、路径、artifact、调用归一化
 - `src/context/`: repo root、state root、AGENTS、skills、ignore 发现
 - `src/config/`: 配置读取、环境变量、runtime config、app paths
-- `src/tasks/`: 持久化 task 真相源
-- `src/team/`: teammate、消息、协议、policy
-- `src/background/`: 后台任务
-- `src/worktrees/`: 目录隔离
-- `src/subagent/`: 一次性子智能体
-- `src/interaction/`: 共享交互控制层与 shell 契约
-- `src/shell/cli/`: CLI shell 输入、输出、turn 展示、intro
+- `src/tasks/`: 持久化 task 真相源
+- `src/team/`: teammate、消息、协议、policy
+- `src/background/`: 后台任务
+- `src/worktrees/`: 目录隔离
+- `src/orchestrator/`: lead 编排、任务图、lifecycle 派生、route / dispatch
+- `src/subagent/`: 一次性子智能体
+- `src/interaction/`: 共享交互控制层与 shell 契约
+- `src/interaction/exitGuard.ts`: 交互退出前的后台进程检查与 kill-or-continue 语义
+- `src/shell/cli/`: CLI shell 输入、输出、turn 展示、intro
 - `src/ui/`: CLI 文本格式化、runtime summary 和兼容导出
 - `src/telegram/`: Telegram 私聊通道、delivery、附件、CLI、process lock
 - `src/weixin/`: Weixin 私聊通道、OpeniLink client、delivery、context_token、CLI、process lock
 
-## 当前 lightweight context 对应代码
-
-- `src/agent/promptSections.ts`: static / dynamic prompt layer
-- `src/agent/toolResultStorage.ts`: externalized tool result 落盘
-- `src/agent/toolResultPreview.ts`: tool payload 预览与 transport 压缩
-- `src/tools/files/toolResultArtifact.ts`: `.athlete/tool-results/...` 的紧凑 artifact read
-- `src/agent/contextBuilder.ts`: 使用轻量 payload 的请求上下文构建
-
-## 当前 checkpoint / continuation 对应代码
-
-- `src/agent/checkpoint.ts`: checkpoint 对外导出面
-- `src/agent/checkpoint/base.ts`: checkpoint 默认结构与从 session 派生
-- `src/agent/checkpoint/state.ts`: checkpoint 归一化与生命周期更新
-- `src/agent/checkpoint/derivation.ts`: completedSteps / nextStep / artifact 推导
-- `src/agent/checkpoint/prompt.ts`: checkpoint 恢复输入与 prompt block
-- `src/agent/turnPersistence.ts`: turn 开始、yield、recovery、tool batch 的 session 持久化接线
-- `src/agent/managedTurn.ts`: continuation 输入通过 checkpoint 生成
-
-## 当前 runtime metrics / 仪表盘 对应代码
-
-- `src/agent/runtimeMetrics.ts`: runtime metrics 对外导出面
-- `src/agent/runtimeMetrics/state.ts`: `runtimeStats` 归一化与事件累积
-- `src/agent/runtimeMetrics/summary.ts`: session runtime summary 生成
-- `src/agent/api.ts`: provider request timing 与 provider usage 采集
-- `src/agent/runTurn.ts`: tool execution、compression、recovery 等运行事件统计接线
-- `src/ui/runtimeSummary.ts`: 交互态 runtime summary 文本格式化
-- `src/interaction/localCommands.ts`: 共享本地命令语义与 `/runtime` / `/stats` / `/仪表盘` 路由
-- `src/ui/localCommands.ts`: CLI 默认输出适配与兼容导出
-
-## 当前交互 shell 对应代码
-
-- `src/interaction/sessionDriver.ts`: 共享交互 session loop、multiline、interrupt、turn 生命周期
-- `src/interaction/shell.ts`: `InteractionShell` / `ShellInputPort` / `ShellOutputPort` / `InteractionTurnDisplay`
+## 当前 lightweight context 对应代码
+
+- `src/agent/promptSections.ts`: prompt facade，对外保留 static / dynamic layer 入口
+- `src/agent/prompt/static.ts`: 静态 operating contract 分块
+- `src/agent/prompt/dynamic.ts`: 动态 runtime 摘要与空状态瘦身
+- `src/agent/prompt/format.ts`: prompt block 渲染与 memory append
+- `src/agent/prompt/structured.ts`: 结构化字段/摘要 section 到 prompt block 的统一渲染
+- `src/agent/prompt/metrics.ts`: prompt layer char / block metrics
+- `src/agent/prompt/requestDiagnostics.ts`: request-time prompt/context diagnostics
+- `src/agent/prompt/types.ts`: prompt layer 类型
+- `src/agent/context.ts`: context / tool-results cluster 入口
+- `src/agent/context/builder.ts`: 使用轻量 payload 的请求上下文构建
+- `src/agent/toolResults/storage.ts`: externalized tool result 落盘
+- `src/agent/toolResults/preview.ts`: tool payload 预览与 transport 压缩
+- `src/tools/files/toolResultArtifact.ts`: `.athlete/tool-results/...` 的紧凑 artifact read
+
+## 当前 checkpoint / continuation 对应代码
+
+- `src/agent/checkpoint.ts`: checkpoint 对外导出面
+- `src/agent/checkpoint/base.ts`: checkpoint 默认结构与从 session 派生
+- `src/agent/checkpoint/state.ts`: checkpoint 归一化与生命周期更新
+- `src/agent/checkpoint/transitions.ts`: checkpoint 上的 yield / recovery / pause / finalize 等转移落盘
+- `src/agent/checkpoint/derivation.ts`: completedSteps / nextStep / artifact 推导
+- `src/agent/checkpoint/prompt.ts`: checkpoint 恢复输入与 prompt block
+- `src/agent/turn.ts`: turn cluster 入口
+- `src/agent/turn/persistence.ts`: turn 开始、yield、recovery、tool batch 的 session 持久化接线
+- `src/agent/turn/managed.ts`: continuation 输入通过 checkpoint 生成
+
+## 当前 runtime transition 对应代码
+
+- `src/agent/runtimeTransition.ts`: runtime transition 对外导出面
+- `src/agent/runtimeTransition/flow.ts`: transition 归一化、checkpoint flow 派生、phase 计算
+- `src/agent/runtimeTransition/builders.ts`: continue / recover / yield / pause / finalize 的结构化 reason builder
+- `src/agent/runtimeTransition/shared.ts`: transition 归一化共享辅助
+
+## 当前 runtime metrics / 仪表盘 对应代码
+
+- `src/agent/runtimeMetrics.ts`: runtime metrics 对外导出面
+- `src/agent/runtimeMetrics/state.ts`: `runtimeStats` 归一化与事件累积
+- `src/agent/runtimeMetrics/summary.ts`: session runtime summary 生成
+- `src/agent/runtimeMetrics/diagnostics.ts`: durable truth / derived diagnostics 拆分与解释生成
+- `src/agent/api.ts`: provider request timing 与 provider usage 采集
+- `src/agent/provider.ts`: provider-specific request body / fallback / recovery policy 下沉
+- `src/agent/runTurn.ts`: tool execution、compression、recovery 等运行事件统计接线
+- `src/ui/runtimeSummary.ts`: 交互态 runtime summary 文本格式化
+- `src/ui/runtimeSummaryData.ts`: `/runtime` 命令的 request-time prompt diagnostics 组装
+- `src/interaction/localCommands.ts`: 共享本地命令语义与 `/runtime` / `/stats` / `/仪表盘` 路由
+- `src/ui/localCommands.ts`: CLI 默认输出适配与薄导出
+
+## 当前 session / task-state 对应代码
+
+- `src/agent/session.ts`: session cluster 入口
+- `src/agent/session/messages.ts`: stored message / chat message 归一化
+- `src/agent/session/store.ts`: session 落盘与恢复
+- `src/agent/session/taskState.ts`: session task-state 提取与 internal reminder
+- `src/agent/session/taskStateHistory.ts`: 从消息历史派生活跃文件、计划动作、完成动作、blocker
+- `src/agent/session/todos.ts`: todo 真相提取、格式化与 normalize
+
+## 当前交互 shell 对应代码
+
+- `src/interaction/sessionDriver.ts`: 共享交互 session loop、multiline、interrupt、turn 生命周期
+- `src/interaction/exitGuard.ts`: 交互退出时列出 background job / teammate worker，并执行 kill-or-continue 分支
+- `src/interaction/shell.ts`: `InteractionShell` / `ShellInputPort` / `ShellOutputPort` / `InteractionTurnDisplay`
 - `src/shell/cli/readlineInput.ts`: CLI 输入适配
 - `src/shell/cli/output.ts`: CLI 文本输出适配
 - `src/shell/cli/turnDisplay.ts`: CLI spinner + stream renderer 适配
@@ -68,18 +109,46 @@
 - `src/mcp/playwright/config.ts`: Playwright MCP 配置归一化与 server args
 - `src/mcp/playwright/paths.ts`: `.athlete/playwright-mcp/` 路径约定
 - `src/mcp/playwright/artifacts.ts`: artifact 目录准备、迁移、生成配置
-- `src/mcp/playwright/invoke.ts`: relative filename 归一化
-- `src/mcp/stdioClient.ts`: 真实 stdio MCP client
-- `src/mcp/toolAdapter.ts`: MCP tool 适配进 Athlete registry
-- `src/tools/runtimeRegistry.ts`: runtime registry 组装 built-in tools 与 MCP tools
-
-## 当前 closeout / verification 对应代码
-
-- `src/agent/finalize.ts`: tool-less turn 的最终收口与 verification / pause 行为
-- `src/agent/closeout.ts`: closeout 阶段的工具过滤与 stale todo 容忍规则
-- `src/agent/verificationState.ts`: verification 真相源
-- `src/agent/verificationSignals.ts`: lightweight verification signals 与 auto-readback
-- `src/agent/runTurn.ts`: 调度这些规则，但不持有它们的内部实现细节
+- `src/mcp/playwright/invoke.ts`: relative filename 归一化
+- `src/mcp/stdioClient.ts`: 真实 stdio MCP client
+- `src/mcp/toolAdapter.ts`: MCP tool 适配进 Athlete registry，并补充治理所需 origin 信息
+- `src/tools/runtimeRegistry.ts`: runtime registry 组装 built-in tools 与 MCP tools，并保留 blocked diagnostics
+- `src/tools/registry.ts`: fail-closed tool registry、entries / blocked 暴露面与 result governance 校验
+
+## 当前 closeout / verification 对应代码
+
+- `src/agent/turn.ts`: closeout / finalize cluster 入口
+- `src/agent/turn/finalize.ts`: tool-less turn 的最终收口与 verification / pause 行为
+- `src/agent/turn/closeout.ts`: closeout 阶段的工具过滤与 stale todo 容忍规则
+- `src/agent/verification.ts`: verification cluster 入口
+- `src/agent/verification/state.ts`: verification 真相源
+- `src/agent/verification/signals.ts`: lightweight verification signals 与 auto-readback
+- `src/agent/acceptance/signals.ts`: `http_endpoint_verified` / `web_page_verified` / `document_read_completed` / `structured_artifact_valid`
+- `src/cli/support.ts`: one-shot closeout report 生成
+- `src/cli.ts`: one-shot terminal closeout JSON 输出
+- `src/agent/runTurn.ts`: 调度这些规则，但不持有它们的内部实现细节
+
+## 当前 turn / loop 辅助代码
+
+- `src/agent/turn.ts`: turn / loop helper cluster 入口
+- `src/agent/turn/recovery.ts`: API 重试、content-policy redaction、context shrink
+- `src/agent/turn/planGate.ts`: mutating tool 的 todo 前置约束
+- `src/agent/turn/loopGuard.ts`: 重复工具调用保护
+- `src/agent/turn/toolExecutor.ts`: tool 执行与 recovery hint
+- `src/agent/turn/toolless.ts`: 缺 skill / finalize 收口分发
+- `src/agent/turn/state.ts`: request 内 turn 状态 prompt block 与进度提示
+
+## 当前任务编排 / lifecycle 对应代码
+
+- `src/orchestrator/prepareLeadTurn.ts`: lead slice 开始前的 orchestrator 入口
+- `src/orchestrator/analyze.ts`: objective / complexity / handoff 意图判断
+- `src/orchestrator/taskPlanning.ts`: 最小任务图落盘
+- `src/orchestrator/taskLifecycle.ts`: 从 task / team / background / worktree 真相源派生 task lifecycle
+- `src/orchestrator/taskLifecycleShared.ts`: lifecycle 构造与 handoff 共享辅助
+- `src/orchestrator/progress.ts`: 读取 durable truth 并构造 progress snapshot
+- `src/orchestrator/route.ts`: 只消费 lifecycle 后的 ready / active / blocked 事实做 route
+- `src/orchestrator/dispatch.ts`: 派工落盘与 fail-closed handoff 检查
+- `src/tools/tasks/claimTaskTool.ts`: teammate claim + worktree fail-closed 入口
 
 ## 当前文档 / 验证位置
 
@@ -88,13 +157,19 @@
 - `spec/modules/lightweight-context-runtime.md`
 - `spec/modules/session-resume-compact.md`
 - `spec/modules/runtime-metrics.md`
-- `tests/playwright-mcp.test.ts`
-- `tests/browser-tool-priority.test.ts`
-- `tests/playwright-workflow-guard.test.ts`
-- `tests/agent-closeout.test.ts`
-- `tests/runtime-lightweight-context.test.ts`
-- `tests/runtime-checkpoint-resume.test.ts`
-- `tests/runtime-observability.test.ts`
+- `tests/playwright-mcp.test.ts`
+- `tests/browser-tool-priority.test.ts`
+- `tests/playwright-workflow-guard.test.ts`
+- `tests/browser-workflow-abstraction.test.ts`
+- `tests/agent-closeout.test.ts`
+- `tests/interaction-shell.test.ts`
+- `tests/provider-capability.test.ts`
+- `tests/document-workflow-abstraction.test.ts`
+- `tests/acceptance-signal.test.ts`
+- `tests/one-shot-cli-result-contract.test.ts`
+- `tests/runtime-lightweight-context.test.ts`
+- `tests/runtime-checkpoint-resume.test.ts`
+- `tests/runtime-observability.test.ts`
 - `scripts/verify-runtime-lightweight-context-api.mjs`
 - `scripts/verify-runtime-checkpoint-api.mjs`
 - `scripts/verify-runtime-observability-api.mjs`

package/spec/interfaces/InteractionShell.md

@@ -18,15 +18,16 @@
 
 ### 当前契约语义
 
-#### `ShellInputPort`
+#### `ShellInputPort`
 
 负责：
 
 - 读取普通输入
 - 读取 multiline 输入
-- 绑定 interrupt 事件
-
-不负责：
+- 绑定 interrupt 事件
+- 为共享 driver 提供退出确认时所需的普通输入
+
+不负责：
 
 - 决定 task / runtime 真相
 - 自己执行 agent turn
@@ -51,9 +52,16 @@
 - 展示流式 assistant / reasoning / tool 状态
 - 在 turn 结束或中断时 flush / dispose
 
-#### `InteractionShell`
-
-负责把上面三部分组装给共享 driver 使用。
+#### `InteractionShell`
+
+负责把上面三部分组装给共享 driver 使用。
+
+共享 driver 可以基于这套输入/输出契约实现：
+
+- 普通命令输入
+- multiline 输入
+- interrupt
+- quit 前二次确认
 
 ## 当前 CLI 实现