chore2.6.13

使用模块级 Set 缓存已注入的 deferred tool 列表，diff 后仅在有
新增工具时重新注入。根因：注入消息追加到 queryModel 的局部变量
messagesForAPI，不写入消息历史，所以每次调用都是首次。

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,52 @@
+---
+name: Bug 报告
+description: 报告一个可复现的 bug
+title: "bug: "
+labels: ["bug"]
+assignees: []
+---
+
+## 发帖前必读
+
+- [ ] 我已经搜索过 [现有 Issues](https://github.com/claude-code-best/claude-code/issues)，没有找到重复。
+- [ ] 我使用的是 **最新版本**（`bun run build` 或最新 release）。
+- [ ] 我已经阅读过 [README](https://github.com/claude-code-best/claude-code) 和相关文档。
+
+**未完成以上检查的 Issue 将被直接关闭。**
+
+---
+
+## 运行环境
+
+| 项目| 值|
+|---|---|
+| 操作系统| 例如 macOS 15.4、Ubuntu 24.04|
+| Bun 版本| 例如 `bun --version` 的输出|
+| Claude Code 版本| 例如 `2.4.3` 或 commit hash|
+| 安装方式| `bun run build` / npm / 其他|
+| 模型| 例如 claude-sonnet-4-6、claude-opus-4-7|
+
+## 复现步骤
+
+1.
+2.
+3.
+
+## 期望行为
+
+<!-- 应该发生什么？ -->
+
+## 实际行为
+
+<!-- 实际发生了什么？如有必要可附截图。 -->
+
+## 相关日志
+
+<!-- 粘贴终端输出或错误信息，请使用 triple backticks 代码块。 -->
+
+```text
+```
+
+## 补充信息
+
+<!-- 其他上下文 — 配置、环境变量、尝试过的 workaround 等。 -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 讨论区
+    url: https://github.com/claude-code-best/claude-code/discussions
+    about: 使用问题、功能建议和一般讨论 — 请使用 Discussions 而非 Issues。
+  - name: 📖 项目文档
+    url: https://github.com/claude-code-best/claude-code
+    about: 提交 issue 前，请先阅读 README 和相关文档，你的问题可能已经有答案了。

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: 功能建议
+description: 提出新功能或改进建议
+title: "feat: "
+labels: ["enhancement"]
+assignees: []
+---
+
+## 发帖前必读
+
+- [ ] 我已经搜索过 [现有 Issues](https://github.com/claude-code-best/claude-code/issues)，没有找到重复。
+- [ ] 这是功能建议，不是 Bug 报告或使用问题。
+- [ ] 使用问题请前往 [Discussions](https://github.com/claude-code-best/claude-code/discussions)。
+
+---
+
+## 要解决的问题
+
+<!-- 这个功能解决什么问题？为什么需要它？ -->
+
+## 建议方案
+
+<!-- 描述你建议的实现方式，尽量简洁具体。 -->
+
+## 考虑过的替代方案
+
+<!-- 还有没有想到的其他实现思路？ -->
+
+## 补充信息
+
+<!-- 截图、草图、参考资料，或其他有助于说明需求的内容。 -->

.github/workflows/publish-npm.yml

@@ -3,11 +3,11 @@ name: Publish to npm
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
   workflow_dispatch:
     inputs:
       version:
-        description: '版本号 (例如: v1.9.0)'
+        description: "版本号 (例如: v1.9.0)"
         required: true
         type: string
 

CLAUDE.md

@@ -78,8 +78,9 @@ bun run docs:dev
 
 - **Runtime**: Bun (not Node.js). All imports, builds, and execution use Bun APIs.
 - **Build**: `build.ts` 执行 `Bun.build()` with `splitting: true`，入口 `src/entrypoints/cli.tsx`，输出 `dist/cli.js` + chunk files。Build 默认启用 19 个 feature（见下方 Feature Flag 段）。构建后自动替换 `import.meta.require` 为 Node.js 兼容版本（产物 bun/node 都可运行）。构建时会将 `vendor/audio-capture/` 和 `src/utils/vendor/ripgrep/` 复制到 `dist/vendor/` 下。
-- **Build (Vite)**: `vite.config.ts` + `scripts/post-build.ts`，chunk 输出到 `dist/chunks/`。post-build 同样复制 vendor 文件到 `dist/vendor/`。
-- **Vendor 路径解析**: 构建后 chunk 文件位于 `dist/` 或 `dist/chunks/` 下，vendor 二进制在 `dist/vendor/`。`src/utils/ripgrep.ts` 和 `packages/audio-capture-napi/src/index.ts` 均通过 `import.meta.url` 路径中 `lastIndexOf('dist')` 定位 dist 根目录，再拼接 `vendor/` 子路径，确保不同构建产物层级下路径一致。
+- **Build (Vite)**: `vite.config.ts` + `scripts/post-build.ts`，代码分割模式，chunk 输出到 `dist/chunks/`。post-build 遍历 `dist/` 和 `dist/chunks/` 下所有 `.js` 文件做 `globalThis.Bun` 解构 patch，复制 vendor 文件到 `dist/vendor/`。
+- **Vendor 路径解析**: 构建后 chunk 文件位于 `dist/` 或 `dist/chunks/` 下，vendor 二进制在 `dist/vendor/`。`src/utils/distRoot.ts` 提供共享的 `distRoot` 函数，通过 `import.meta.url` 路径中 `lastIndexOf('dist')` 或 `lastIndexOf('src')` 定位根目录。`ripgrep.ts`、`computerUse/setup.ts`、`claudeInChrome/setup.ts`、`updateCCB.ts` 均使用 `distRoot` 而非内联 `import.meta.url` 路径推算。`packages/audio-capture-napi/src/index.ts` 有独立的 `lastIndexOf('dist')` 逻辑，功能等价。
+- **为什么 Vite 必须代码分割**: Bun/JSC 会全量解析单个大 JS 文件的 bytecode 和 JIT，单文件 17MB 产物导致 RSS 暴涨至 ~1GB（Node/V8 懒解析仅需 ~220MB）。代码分割为 600+ 小 chunk 后 Bun 按需加载，`--version` RSS 从 966MB 降至 35MB，完整加载从 1GB+ 降至 ~500MB。
 - **Dev mode**: `scripts/dev.ts` 通过 Bun `-d` flag 注入 `MACRO.*` defines，运行 `src/entrypoints/cli.tsx`。默认启用全部 feature。
 - **Module system**: ESM (`"type": "module"`), TSX with `react-jsx` transform.
 - **Monorepo**: Bun workspaces — 17 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。

README.md

@@ -10,12 +10,11 @@
 
 > Which Claude do you like? The open source one is the best.
 
-牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI 工具的源码反编译/逆向还原项目。目标是将 Claude Code 大部分功能及工程化能力复现 (问就是老佛爷已经付过钱了)。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 实现技术普惠
+牢 A (Anthropic) 官方 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 完整复原的工程化项目。虽然很难绷, 但是它叫做 CCB(踩踩背)... 而且, 我们实现了企业版或者需要登陆 Claude 账号才能使用的特性, 并在此基础上扩展了更多好玩的特性。
 
-> 我们将会在五一期间进行整个代码仓库的 lint 规范化, 这个期间提交的 PR 可能会有非常多的冲突, 所以大的功能请尽量在这之前提交哈
-
-[文档在这里, 支持投稿 PR](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组](https://discord.gg/uApuzJWGKX)
+[Peri Code](https://github.com/KonghaYao/peri)：Claude Code 兼容的 Rust Agent，多年大模型经验匠心制作，国内大模型（DeepSeek/GLM）精调，CPU/内存极致优化，在开发版/树莓派上也能跑 CC 一样的体验。
 
+[文档在这里](https://ccb.agent-aura.top/) | [留影文档在这里](./Friends.md) | [Discord 群组，群主在线答疑](https://discord.gg/uApuzJWGKX)
 
 | 特性                        | 说明                                                                                                                         | 文档                                                                                                                                      |
 | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
@@ -150,7 +149,6 @@ bun run build
 
 需要填写的字段：
 
-
 | 📌 字段      | 📝 说明       | 💡 示例                      |
 | ------------ | ------------- | ---------------------------- |
 | Base URL     | API 服务地址  | `https://api.example.com/v1` |

docs.json

@@ -87,6 +87,7 @@
           "docs/internals/sentry-setup",
           "docs/internals/hidden-features",
           "docs/internals/ant-only-world",
+          "docs/internals/session-transcript-persistence",
           "docs/features/debug-mode",
           "docs/features/buddy"
         ]

docs/agent/coordinator-and-swarm.mdx

@@ -1,86 +1,216 @@
 ---
-title: "协调者与蜂群模式 - 多 Agent 高级编排"
-description: "从源码角度解析 Claude Code 多 Agent 协作：Coordinator Mode 的 System Prompt 设计、Worker 生命周期、Task 通信协议和 Swarm 蜂群的任务分配机制。"
-keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "多 Agent 协作", "任务编排"]
+title: "协调者与蜂群模式：多 Agent 编排机制"
+description: "从源码角度拆解 Claude Code 的 Coordinator Mode、Agent Teams / Swarm、subagent、teammate、Mailbox、Task 工具、runtime task、状态恢复与排障路径。"
+keywords: ["协调者模式", "蜂群模式", "Agent Swarm", "Agent Teams", "多 Agent 协作", "任务编排", "Mailbox", "Subagent"]
 ---
 
-{/* 本章目标：从源码角度揭示 Coordinator Mode 和 Agent Swarms 的架构设计 */}
+Claude Code 里有很多看起来都叫“多 Agent”的东西：`Agent` 工具、fork agent、Coordinator Mode、Agent Teams / Swarm、remote agent、后台 runtime task、`TaskCreate` 任务白板。它们共享部分底层设施，但不是同一个抽象。
 
-## 两种协作模式的架构差异
+这篇文档解决的是跨机制理解问题：当你看到一个任务被“派出去”、一个 teammate 变成 idle、一个 `<task-notification>` 回到主线程、一个 team 目录还在但 teammate 不跑了，应该知道它属于哪套机制、状态放在哪里、通信走哪条路、哪些东西能恢复。
 
-| 维度 | Coordinator Mode | Agent Swarms |
-|------|-----------------|--------------|
-| **门控** | `feature('COORDINATOR_MODE')` + `CLAUDE_CODE_COORDINATOR_MODE=1` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 环境变量 |
-| **拓扑** | 星型：Coordinator 居中，Worker 外围 | 星型+P2P 混合：Team Lead 协调，Teammate 间可直接通信 |
-| **角色** | 明确分工：Coordinator 编排、Worker 执行 | Team Lead 协调 + Teammate 自主认领任务 |
-| **通信** | `SendMessage` 定向通信 + `<task-notification>` | Mailbox 消息系统（message / broadcast） |
-| **适用** | 需要集中决策的复杂任务 | 并行度高、需要 Teammate 间直接协作的任务 |
+## 全局心智模型
 
-两者不是互斥的——理论上 Coordinator Mode 可以在 Agent Teams 架构之上运行（概念层叠加，非嵌套团队），将 Coordinator 作为特殊的 Team Lead，但这部分集成（`workerAgent.ts` 中的 `getCoordinatorAgents`）目前为 stub 实现，尚未完整落地。
+最短心智模型是：
 
-## Coordinator Mode：星型编排架构
-
-### 激活机制
-
-```typescript
-// src/coordinator/coordinatorMode.ts:36
-export function isCoordinatorMode(): boolean {
-  if (feature('COORDINATOR_MODE')) {
-    return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
-  }
-  return false  // 外部构建始终 false
-}
+```text
+Agent 是派人干活。
+TaskCreate 是往白板上贴任务卡。
+Runtime Task 是正在跑的人或远端人影。
+Coordinator 是星型编排器。
+Swarm 是有成员、有邮箱、有任务白板的团队。
 ```
 
-Coordinator Mode 需要双重门控：构建时 `feature('COORDINATOR_MODE')` 和运行时环境变量。`matchSessionMode()` 在会话恢复时自动同步模式状态——如果恢复的会话是 coordinator 模式，它会翻转环境变量以确保一致性。
+先把几个词压平：
 
-### Coordinator 的工具集
+| 概念 | 本质 | 入口 | 状态位置 | 结果回路 |
+|---|---|---|---|---|
+| 普通 sync subagent | 一次性前台 `Agent` tool call | `Agent({ subagent_type })` | foreground `LocalAgentTask` | 当前 turn 的 `tool_result` |
+| 普通 async subagent | 一次性后台 agent | `Agent({ subagent_type, async: true })` 或自动后台化 | `AppState.tasks` + sidechain | `async_launched` + `<task-notification>` |
+| fork agent | 继承父上下文和 exact tools 的后台分支 | 省略 `subagent_type` 且 fork gate 满足 | `LocalAgentTask` + `.meta.json` | `<task-notification>` |
+| coordinator worker | Coordinator 派出的 `worker` async subagent | Coordinator 调 `Agent({ subagent_type: "worker" })` | `LocalAgentTask` | `<task-notification>` + `SendMessage(to: agentId)` |
+| swarm teammate | 长生命周期团队成员 | `Agent({ name, team_name?, prompt })` | `InProcessTeammateTask` 或 pane member | mailbox by name，可 idle 后继续 |
+| remote agent | 远端执行体的本地镜像 | `Agent(..., isolation: "remote")` | `RemoteAgentTask` + remote sidecar | CCR events / polling |
+| work item task | 共享任务白板条目 | `TaskCreate/Update/List/Get` | `~/.claude/tasks/<taskListId>/*.json` | teammate / lead 认领和更新 |
+| runtime task | 正在运行或曾运行的后台执行体 | agent、shell、workflow、remote 等入口 | `AppState.tasks` | UI、spinner、resume、kill |
 
-Coordinator 被剥夺了所有"动手"工具，只保留编排能力：
+## 系统分层
 
-| 工具 | 用途 |
-|------|------|
-| **Agent** | 启动新 Worker（`subagent_type: "worker"`） |
-| **SendMessage** | 向已有 Worker 发送后续指令 |
-| **TaskStop** | 中途停止走错方向的 Worker |
-| **subscribe_pr_activity** | 订阅 GitHub PR 事件（review comments、CI 结果） |
+多 Agent 系统可以看成五层，每层回答一个问题：
 
-Coordinator **不写代码、不读文件、不执行命令**——它的核心职责是：理解需求、分配任务、综合结果，以及在无需工具时直接回答用户问题。
+| 层 | 回答的问题 | 典型对象 |
+|---|---|---|
+| 入口层 | 用户或模型通过什么工具启动动作 | `/coordinator`、`AgentTool`、`TeamCreate`、`SendMessage`、`TaskUpdate` |
+| 编排层 | 谁负责拆解、派发、控制和综合 | Coordinator、Team Lead、AgentTool routing |
+| 运行层 | 谁真正执行或代表执行状态 | `LocalAgentTask`、`InProcessTeammateTask`、`RemoteAgentTask` |
+| 通信层 | 结果和控制信号如何回流 | `tool_result`、`<task-notification>`、mailbox、CCR events |
+| 持久化层 | 进程重启后还能看见什么 | session JSONL、sidechain、team config、task files、inbox、sidecar meta |
 
-### Worker 的工具权限
-
-Worker 的可用工具由 `getCoordinatorUserContext()`（`coordinatorMode.ts:80`）动态注入到 System Prompt：
-
-```typescript
-// 简化模式下：只有 Bash + Read + Edit
-const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
-  ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]
-  : Array.from(ASYNC_AGENT_ALLOWED_TOOLS)
-      .filter(name => !INTERNAL_WORKER_TOOLS.has(name))
+```mermaid
+flowchart TD
+  A["入口层<br/>slash command / AgentTool / Team tools / SendMessage"] --> B["编排层<br/>Coordinator / Team Lead / AgentTool routing"]
+  B --> C["运行层<br/>LocalAgentTask / RemoteAgentTask / InProcessTeammateTask"]
+  C --> D["通信层<br/>tool_result / task-notification / mailbox / CCR events"]
+  D --> E["持久化层<br/>session JSONL / sidechain / team config / tasks / inboxes / sidecar meta"]
 ```
 
-`INTERNAL_WORKER_TOOLS`（TeamCreate、TeamDelete、SendMessage、SyntheticOutput）被显式排除——Worker 不能嵌套创建团队或发送消息，防止不可控的递归。
+这五层不是一一对应关系。Coordinator worker 在运行层是 `LocalAgentTask`，通信层靠 `<task-notification>` 和 `SendMessage(to: agentId)`；Swarm teammate 在运行层可能是 `InProcessTeammateTask`，通信层靠 mailbox；remote agent 在运行层是本地 `RemoteAgentTask` 镜像，真实执行状态来自 CCR。
 
-### Scratchpad：跨 Worker 的共享知识库
+## 什么时候用哪套机制
 
-当 `isScratchpadGateEnabled()`（内部检查 `tengu_scratch` feature gate）启用时，Workers 获得一个 Scratchpad 目录，Coordinator 通过其系统上下文知晓该目录的存在：
+| 场景 | 推荐机制 | 为什么 |
+|---|---|---|
+| 需要一个主脑拆解、派发、综合、纠偏 | Coordinator Mode | 主线程被限制为编排器，减少直接上手乱改。 |
+| 多个任务相对独立，需要长期队友持续领任务 | Agent Teams / Swarm | 有 team config、mailbox、shared task list。 |
+| 只想派一个专家研究或修改 | 普通 subagent | 成本低、模型路径短、结果直接回当前 turn 或后台通知。 |
+| 想复制当前上下文做并行探索 | fork agent | 继承父上下文和 exact tools，适合分支探索。 |
+| 想把工作放到远端环境执行 | remote agent | 本地只保留 `RemoteAgentTask` 镜像，执行在 CCR。 |
 
-```
-Scratchpad 目录：
-  - Workers 可自由读写，无需权限审批
-  - 用于持久化的跨 Worker 知识
-  - 结构由 Coordinator 决定（无固定格式）
+两个常见误判：
+
+| 误判 | 更好的选择 |
+|---|---|
+| “我要并行，所以一定用 Swarm” | 如果只是一次性研究/验证，用 async subagent 或 Coordinator worker 更轻。 |
+| “我要团队，所以 Coordinator 就够了” | 如果需要成员持续认领共享任务、互相发消息、保留 team 状态，用 Swarm。 |
+
+## 两种多 Agent 拓扑
+
+Coordinator 和 Swarm 都是多 Agent，但控制权和状态模型完全不同。
+
+```mermaid
+flowchart LR
+  subgraph CoordinatorMode["Coordinator Mode"]
+    U1["用户"] --> C["Coordinator 主 Claude"]
+    C -->|Agent worker| W1["worker A<br/>LocalAgentTask"]
+    C -->|Agent worker| W2["worker B<br/>LocalAgentTask"]
+    W1 -->|task-notification| C
+    W2 -->|task-notification| C
+    C -->|SendMessage to agentId| W1
+  end
+
+  subgraph SwarmMode["Agent Teams / Swarm"]
+    U2["用户"] --> L["Team Lead"]
+    L --> TF["TeamFile config.json"]
+    L --> TB["Shared TaskList"]
+    L -->|Agent name| T1["teammate researcher"]
+    L -->|Agent name| T2["teammate tester"]
+    T1 <--> M1["Mailbox inbox JSON"]
+    T2 <--> M2["Mailbox inbox JSON"]
+    T1 --> TB
+    T2 --> TB
+  end
 ```
 
-这是一个关键的协作原语——Worker A 的研究结果可以写入 Scratchpad，Worker B 直接读取，无需通过 Coordinator 中转。
+| 维度 | Coordinator Mode | Agent Teams / Swarm |
+|---|---|---|
+| 拓扑 | 星型：Coordinator 居中，worker 外围 | 团队型：Team Lead + named teammates + mailbox + task list |
+| 主 Claude 角色 | 只编排，不直接执行 | 可以直接执行，也可以作为 team lead 管理团队 |
+| 执行者 | built-in `worker` async subagent | teammate，可能是 in-process，也可能是 pane-based |
+| 通信方式 | `<task-notification>`，必要时 `SendMessage(to: agentId)` | mailbox by name，支持 P2P、broadcast、structured protocol |
+| 任务协作 | 不以 `TeamCreate/TaskList` 为核心 | `TeamFile` + shared task list + mailbox |
+| 恢复模型 | mode 在主 transcript，worker 是 local agent sidechain | team/task/inbox 文件可保留；in-process runner 不完整恢复 |
 
-### `<task-notification>` 通信协议
+Coordinator Mode 不是 Swarm 的特殊 Team Lead。它共享 `AgentTool`、`LocalAgentTask`、`SendMessage` 等设施，但不使用 `TeamCreate/TeamDelete/TaskList/TaskUpdate` 作为核心团队协作机制。
 
-Worker 完成后，Coordinator 收到 XML 格式的通知：
+## Coordinator Mode 五段状态机
+
+Coordinator Mode 的核心设计是把主 Claude 降级为编排器：主线程不直接 `Read/Edit/Bash`，而是拆任务、派 worker、综合结果、必要时停止或继续 worker。
+
+### 1. 启用状态机
+
+```mermaid
+flowchart TD
+  A["feature COORDINATOR_MODE?"] -->|no| B["Coordinator unavailable"]
+  A -->|yes| C["/coordinator command"]
+  C --> D{"target mode?"}
+  D -->|enable| E["set CLAUDE_CODE_COORDINATOR_MODE=1"]
+  D -->|disable| F["delete CLAUDE_CODE_COORDINATOR_MODE"]
+  E --> G["save mode metadata"]
+  F --> G
+  G --> H["inject mode reminder"]
+```
+
+两层条件都满足才算进入 Coordinator：
+
+| 条件 | 作用 |
+|---|---|
+| `feature("COORDINATOR_MODE")` | 构建/运行 feature gate。 |
+| `CLAUDE_CODE_COORDINATOR_MODE=1` | 当前进程实际进入 coordinator。 |
+
+### 2. 恢复状态机
+
+Coordinator mode 是会话属性，写在主 session JSONL 的 `mode` entry 中：
+
+```jsonl
+{"type":"mode","sessionId":"...","mode":"coordinator"}
+```
+
+resume 时会把当前环境和 transcript 中的 mode 对齐：
+
+```mermaid
+flowchart TD
+  A["load transcript mode metadata"] --> B{"env matches transcript mode?"}
+  B -->|yes| C["continue"]
+  B -->|no, transcript=coordinator| D["set CLAUDE_CODE_COORDINATOR_MODE=1"]
+  B -->|no, transcript=normal| E["delete CLAUDE_CODE_COORDINATOR_MODE"]
+  D --> F["emit warning + refresh agent definitions"]
+  E --> F
+```
+
+这避免用户在 normal 环境恢复 coordinator 会话，或反过来把普通会话误当 coordinator 运行。
+
+### 3. Prompt 状态机
+
+Coordinator prompt 不是只看 env。交互 REPL 侧大致优先级是：
+
+| 优先级 | 来源 | 说明 |
+|---|---|---|
+| 1 | override system prompt | 最高优先级。 |
+| 2 | coordinator prompt | `isCoordinatorMode()` 且没有 `mainThreadAgentDefinition` 时使用。 |
+| 3 | main-thread agent prompt | `--agent` / settings agent。 |
+| 4 | custom/default prompt | 普通主线程 prompt。 |
+| 5 | append prompt | 追加型补充。 |
+
+风险点是 `--agent` 和 Coordinator 混用：可能出现工具池已经按 coordinator 过滤，但 system prompt 不是 coordinator 的不一致。
+
+Headless 也要单独看。当前 headless 路径明确做了 coordinator 工具过滤，并注入 coordinator user context；但 system prompt 组装路径和交互 REPL 不完全相同，应把它当成需要复核的边界，而不是默认等同交互路径。
+
+### 4. 工具过滤状态机
+
+Coordinator 主线程和 worker 的工具池不同：
+
+| 角色 | 工具池 | 设计目的 |
+|---|---|---|
+| Coordinator 主线程 | `Agent`、`SendMessage`、`TaskStop`、`SyntheticOutput`、PR activity 订阅类 MCP 工具 | 只编排，不直接执行。 |
+| worker | `ASYNC_AGENT_ALLOWED_TOOLS`，排除 `TeamCreate`、`TeamDelete`、`SendMessage`、`SyntheticOutput` | 执行任务，但不能继续嵌套编排。 |
+| simple mode worker | `Bash`、`Read`、`Edit` | 降低工具面，适合简单执行路径。 |
+| MCP 工具 | 按已连接 server 注入 worker context | 让 worker 能使用外部能力，但由工具池控制边界。 |
+| scratchpad | gate 开启时提供 scratchpad 目录 | 允许跨 worker 共享临时知识。 |
+
+交互路径主要走 `mergeAndFilterTools()`；headless 路径会在主入口直接应用 coordinator 工具过滤；worker 工具池由 `AgentTool` 独立组装，不继承主线程被过滤后的工具池。
+
+### 5. Worker lifecycle
+
+Coordinator 下 `Agent(worker)` 会被强制异步：
+
+```mermaid
+flowchart TD
+  A["Coordinator calls Agent(worker)"] --> B["AgentTool marks shouldRunAsync"]
+  B --> C["registerAsyncAgent"]
+  C --> D["runAsyncAgentLifecycle"]
+  D --> E{"final status"}
+  E -->|completed| F["enqueue completed task-notification"]
+  E -->|failed| G["enqueue failed task-notification"]
+  E -->|killed| H["enqueue killed task-notification"]
+  F --> I["command queue injects into next turn"]
+  G --> I
+  H --> I
+```
+
+`<task-notification>` 是 user-role message，但不是用户输入。Coordinator prompt 必须把它当成 worker 结果信号：
 
 ```xml
 <task-notification>
-  <task-id>agent-a1b</task-id>          ← Worker 的 agentId
+  <task-id>agent-a1b</task-id>
   <status>completed|failed|killed</status>
   <summary>Agent "Investigate auth bug" completed</summary>
   <result>Found null pointer in src/auth/validate.ts:42...</result>
@@ -92,160 +222,430 @@ Worker 完成后，Coordinator 收到 XML 格式的通知：
 </task-notification>
 ```
 
-通知以 `user-role message` 形式送达，Coordinator 通过 `<task-notification>` 标签区分它和用户消息。`<task-id>` 用于 `SendMessage` 的 `to` 参数，实现定向续传。
+Coordinator 的关键约束是“综合而不是转发”。worker 看不到用户和 coordinator 的完整对话，所以 prompt 必须自包含：
 
-### Coordinator 的核心职责：综合（Synthesis）
-
-Coordinator System Prompt（`coordinatorMode.ts:111-369`，约 260 行）明确要求 Coordinator **不能懒惰地委派理解**：
-
-```
-反模式（禁止）：
-  "Based on your findings, fix the auth bug"
-  → 把理解的责任推给了 Worker
-
-正确做法：
-  "Fix the null pointer in src/auth/validate.ts:42.
-   The user field on Session (src/auth/types.ts:15) is
-   undefined when sessions expire but the token remains cached.
-   Add a null check before user.id access."
-  → Coordinator 自己理解了问题，给出精确指令
+```text
+Fix the null pointer in src/auth/validate.ts:42.
+Session.user can be undefined when the session expires but the token remains cached.
+Add a null check before user.id access; if null, return 401 with "Session expired".
+Run validate.test.ts and report the commit hash.
 ```
 
-这是 Coordinator Mode 最核心的设计约束：Coordinator 必须先理解，再分配。
+反模式是：
 
-## Agent Teams (Swarm)：蜂群式协作
-
-Swarm 模式基于任务系统 V2（详见[任务管理](../tools/task-management.mdx)），核心机制是**共享任务列表 + 竞争认领 + Mailbox 消息系统**：
-
-### 团队初始化
-
-```
-Team Lead 创建团队（TeamCreateTool）
-  ↓
-设置 teamName → setLeaderTeamName()
-  ↓
-所有 Teammate 自动获得相同的 taskListId
-  ↓
-Teammate 启动时：
-  1. CLAUDE_CODE_TASK_LIST_ID 环境变量（显式覆盖）
-  2. Teammate 上下文的 teamName（共享 Lead 的任务列表）
-  3. CLAUDE_CODE_TEAM_NAME 环境变量
-  4. Lead 设置的 teamName
-  5. getSessionId()（兜底）
+```text
+Based on your findings, fix it.
 ```
 
-多级优先级确保了 Team Lead 和所有 Teammate 指向同一个任务列表，无需额外协调。
+### Coordinator 边界与排错
 
-### 架构组件
+| 现象 | 可能原因 | 处理方式 |
+|---|---|---|
+| Coordinator 主线程不能读文件或跑命令 | 工具池被过滤，这是预期行为 | 派 `worker`，把文件、错误、验收标准写入 worker prompt。 |
+| `--agent` 后 coordinator 行为不一致 | agent prompt 优先级压过 coordinator prompt，但工具仍可能被过滤 | 避免混用，或确认当前 system prompt 来源。 |
+| worker 还在跑但方向错 | runtime task 仍是 `running` | 用 `TaskStop` 停止；会产生 `killed` notification。 |
+| worker 完成但结论不够 | 已经结束的一次性 async agent | 更推荐 fresh worker；只有需要保留 sidechain 时才 `SendMessage` 续跑。 |
+| `SendMessage` 失败 | 找不到 agent、缺 sidechain transcript、message 缺 `summary` | 查 agentId/name、sidechain `.jsonl/.meta.json`，plain text message 记得带 `summary`。 |
+| coordinator 下没有 `worker` | non-interactive 下禁用了 built-in agents | 检查 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。 |
 
-官方 Agent Teams 架构定义了四个核心组件：
+## Swarm 完整状态机
 
-| 组件 | 角色 |
-|------|------|
-| **Team Lead** | 创建团队、分配任务、综合结果的主 Claude Code 会话 |
-| **Teammate** | 独立的 Claude Code 实例，各自拥有独立的上下文窗口 |
-| **Task List** | 共享的任务列表，Teammate 竞争认领和完成 |
-| **Mailbox** | 消息系统，支持 Teammate 间直接通信 |
+Swarm 的核心是团队，而不是一次 `Agent` 调用。`TeamCreate` 建 team，`Agent({ name })` 加 teammate，`TaskCreate/Update/List/Get` 提供任务白板，`SendMessage` 和 mailbox 提供通信与控制。
 
-### Mailbox 消息系统
+当前实现默认启用 Agent Teams；设置 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS_DISABLED` 才会关闭。
 
-官方架构中的 Mailbox 是 Teammate 间通信的核心原语，支持两种消息模式（`broadcast` 模式来自源码推断，官方文档未明确细分）：
+### 团队生命周期
 
-| 模式 | 作用 | 场景 |
-|------|------|------|
-| **message** | 定向发送给指定 Teammate | 传递具体指令、请求协作 |
-| **broadcast** | 广播给所有 Teammate | 全局通知、状态同步 |
-
-Mailbox 的关键特性：
-- **自动投递**：消息自动送达目标 Teammate 的对话上下文
-- **空闲通知**（TeammateIdle）：Teammate 完成当前任务进入空闲时，自动通过 Mailbox 通知 Team Lead
-- **直接通信**：与 Coordinator Mode 不同，Teammate 之间可以直接通信，无需经过 Lead 中转
-
-### Hook 事件
-
-Agent Teams 提供三个关键 Hook 事件，用于在团队生命周期中注入自定义逻辑：
-
-| Hook | 触发时机 | 典型用途 |
-|------|---------|---------|
-| **TaskCreated** | 新任务添加到任务列表时 | 自动分配、优先级排序 |
-| **TaskCompleted** | 任务标记为完成时 | 结果通知、依赖解锁 |
-| **TeammateIdle** | Teammate 完成所有任务进入空闲时 | Lead 重新分配、动态扩缩容 |
-
-### 限制
-
-当前 Agent Teams 实现的限制：
-- **不支持嵌套团队**：Teammate 不能再创建子团队
-- **每 session 一个团队**：一个会话只能属于一个团队
-- **Lead 固定**：Team Lead 创建后不可更换
-- **不支持 in-process Teammate 的会话恢复**：进程重启后 in-process 类型 Teammate 的状态丢失
-
-### 持久化存储
-
-团队状态通过文件系统持久化，确保进程重启后可恢复：
-
-```
-~/.claude/teams/{team-name}/config.json   ← 团队配置
-~/.claude/tasks/{team-name}/              ← 共享任务列表（文件锁保护）
+```mermaid
+flowchart TD
+  A["NoTeam"] -->|TeamCreate| B["TeamReady leader"]
+  B -->|AgentTool name + team| C["SpawnResolving"]
+  C --> D{"backend"}
+  D -->|in-process| E["InProcessTeammateTask registered"]
+  D -->|pane-based| F["terminal pane spawned"]
+  E --> G["TeamMemberRegistered"]
+  F --> G
+  G --> H["TeammateRunning"]
+  H -->|turn complete| I["IdleNotification"]
+  I --> J["TeammateIdle"]
+  J -->|mailbox message| H
+  J -->|unowned unblocked task| K["claim task + TaskUpdate in_progress"]
+  K --> H
+  H -->|shutdown_request| L["model approves or rejects"]
+  J -->|shutdown_request| L
+  L -->|approved| M["cleanup member / unassign task"]
+  L -->|rejected| J
+  B -->|TeamDelete| N["request active teammate shutdown"]
+  N --> O["wait optional wait_ms"]
+  O --> P["cleanup team dir / task dir / AppState"]
+  P --> A
 ```
 
-### 任务认领与竞争
+关键不变量：
 
-`claimTask()` 是 Agent Teams 的核心并发原语：
+| 不变量 | 含义 |
+|---|---|
+| roster 扁平 | teammate 内禁止再 spawn teammate，避免团队嵌套。 |
+| mailbox 按 name 寻址 | inbox 路径是 `teamName + agentName`，不是 agentId。 |
+| task list 是共享白板 | `TaskCreate` 只写 pending task，不启动执行体。 |
+| shutdown 不是强杀 | shutdown request 会交给模型处理，approve 后才 graceful shutdown。 |
+| TeamFile 是跨进程事实源 | `AppState.teamContext` 是 leader UI 的投影。 |
 
-```
-Teammate A 调用 TaskList → 发现 task #3 是 pending
-Teammate B 同时发现 task #3 是 pending
-  ↓
-两者同时尝试 TaskUpdate(task #3, {status: "in_progress"})
-  ↓
-文件锁保证原子性：
-  - 第一个写入者获得 owner 锁定
-  - 第二个写入者收到 already_claimed 错误
-  ↓
-获得任务的 teammate 执行工作
-  ↓
-完成后 TaskUpdate(task #3, {status: "completed"})
-  → 依赖此任务的其他任务自动解锁
-  → tool_result 提示 "Call TaskList to find your next task"
+### 存储拓扑
+
+Swarm 的核心状态在 `~/.claude/teams` 和 `~/.claude/tasks`：
+
+```text
+~/.claude/
+  teams/
+    <team-name>/
+      config.json
+      inboxes/
+        <agent-name>.json
+  tasks/
+    <team-name>/
+      .highwatermark
+      1.json
+      2.json
+      ...
 ```
 
-### Teammate 的生命周期管理
+| 文件或结构 | 内容 |
+|---|---|
+| `TeamFile` | `name`、`leadAgentId`、`leadSessionId`、`hiddenPaneIds`、`teamAllowedPaths`、`members[]`。 |
+| `TeamFile.members[]` | `agentId`、`name`、`agentType`、`model`、`color`、`backendType`、`isActive`、`mode`、`worktreePath`、`sessionId`。 |
+| task JSON | `id`、`subject`、`description`、`activeForm`、`owner`、`status`、`blocks`、`blockedBy`、`metadata`。 |
+| mailbox JSON | 普通消息、协议消息、已读状态、颜色和摘要等。 |
 
-```
-Teammate 异常退出
-  ↓
-unassignTeammateTasks()
-  → 扫描任务列表，找到 owner === teammateName 的未完成任务
-  → 重置为 pending + owner=undefined
-  ↓
-Team Lead 感知途径：
-  1. 任务状态变化（pending 重置）—— 通过共享任务列表
-  2. Mailbox 空闲通知（TeammateIdle hook）—— Teammate 停止时自动通知 Lead
-  ↓
-Team Lead 重新分配任务或创建新 Teammate
+### TeamCreate 到 teammate 的链路
+
+```mermaid
+sequenceDiagram
+  participant L as TeamLead
+  participant TC as TeamCreate
+  participant TF as TeamFile
+  participant TL as TaskList
+  participant A as AgentTool
+  participant B as Backend
+  participant M as Mailbox
+
+  L->>TC: create team
+  TC->>TF: write config with lead member
+  TC->>TL: reset task list
+  TC->>L: set leader team context
+  L->>A: Agent with teammate name
+  A->>B: spawn in-process or pane
+  B->>TF: append member
+  B->>M: write initial prompt if needed
+  B->>L: teammate spawned
 ```
 
-## 任务类型全景
+`TeamCreate` 不只是写 `config.json`。它还会注册 session cleanup、重置 team 对应 task list、设置 `leaderTeamName`，并把 leader 投影到 `AppState.teamContext`。
 
-支撑多 Agent 协作的是 7 种任务类型（`src/tasks/types.ts`）：
+`AgentTool` 遇到 `team_name/current teamContext + name` 时走 teammate spawn 分支，不走普通 `runAgent()`。`spawnTeammate()` 会解析 team、唯一化 name、选择 backend、更新 `AppState.teamContext.teammates`，再追加 `TeamFile.members`。
 
-| 任务类型 | 运行位置 | 状态管理 | 适用场景 |
-|----------|---------|---------|---------|
-| **LocalAgentTask** | 本地子进程 | `LocalAgentTaskState` | 标准子 Agent 任务 |
-| **LocalShellTask** | 本地 shell | `LocalShellTaskState` | 后台 shell 命令 |
-| **InProcessTeammateTask** | 同进程内 | `InProcessTeammateTaskState` | 轻量级进程内队友 |
-| **RemoteAgentTask** | 远程服务器 | `RemoteAgentTaskState` | 分布式 Agent（CCR） |
-| **DreamTask** | 后台静默 | `DreamTaskState` | 后台自主整理记忆 |
-| **LocalWorkflowTask** | 本地 | `LocalWorkflowTaskState` | 工作流编排 |
-| **MonitorMcpTask** | 本地 | `MonitorMcpTaskState` | MCP 监控任务 |
+### in-process vs pane-based teammate
 
-`InProcessTeammateTask` 与 `LocalAgentTask` 的关键差异：前者共享进程的内存空间和基础设施状态（如 MCP 连接池），但有独立的对话上下文和工具权限；后者是完全隔离的子进程，启动开销更大但更安全。
+| 维度 | in-process teammate | pane-based teammate |
+|---|---|---|
+| 运行位置 | leader 同进程 | 独立终端 pane / CLI 进程 |
+| 启动方式 | 注册 `InProcessTeammateTask`，启动 `runInProcessTeammate()` | 创建 tmux / iTerm2 / Windows Terminal pane |
+| 消息消费 | runner 自己约 500ms poll mailbox | leader / teammate 侧 `useInboxPoller()` 约 1s poll |
+| 输入路径 | teammate view 输入进入 `pendingUserMessages` | 普通 mailbox prompt 进入 teammate 进程 |
+| 处理优先级 | shutdown > team-lead message > peer message > unowned task claim | poller 按消息类型路由，空闲时自动开一轮 |
+| UI | spinner tree、footer pills、detail dialog、teammate transcript view | footer TeamStatus、TeamsDialog、pane 状态 |
+| 恢复 | runner、AbortController、pending queue 在内存，进程重启不能完整恢复 | pane 进程可能还在；leader 侧 backend map 不持久化，恢复是 best-effort |
+| 删除 | 需要当前 AppState task / AbortController | 通过 backend 写 shutdown request，等待 teammate approve / cleanup |
 
-## Coordinator vs Agent Teams 的选择
+## AgentTool 分流决策树
 
-| 场景 | 推荐模式 | 原因 |
-|------|---------|------|
-| "重构认证系统，需要多模块协调" | Coordinator | 需要集中决策，Worker 间有依赖 |
-| "修复 10 个独立的 lint 警告" | Agent Teams | 任务独立，Teammate 可完全并行 |
-| "研究方案 A 和方案 B，然后选一个实现" | Coordinator | 先并行研究，再集中决策 |
-| "在大仓库中搜索所有 TODO 并分类" | Agent Teams | 无依赖，各自领任务即可 |
+`AgentTool.call()` 是多 Agent 入口最复杂的分叉点。同一个 `Agent` 工具会根据参数和上下文走不同运行时：
+
+```mermaid
+flowchart TD
+  A["AgentTool.call"] --> B{"name + team context?"}
+  B -->|yes| C["spawnTeammate"]
+  B -->|no| D{"isolation=remote?"}
+  D -->|yes| E["registerRemoteAgentTask"]
+  D -->|no| F{"fork route?"}
+  F -->|yes| G["register async LocalAgentTask as fork"]
+  F -->|no| H{"shouldRunAsync?"}
+  H -->|yes| I["register async LocalAgentTask"]
+  H -->|no| J["foreground LocalAgentTask + tool_result"]
+```
+
+| 路由 | 触发条件 | 结果 |
+|---|---|---|
+| teammate | 有 `name`，且存在 `team_name` 或当前 `teamContext` | `spawnTeammate()`，返回 `teammate_spawned`。 |
+| remote | `isolation: "remote"` | 注册 `RemoteAgentTask`，本地保存 remote sidecar。 |
+| fork | 省略 `subagent_type` 且 fork gate/上下文允许 | 强制后台 local agent，继承父上下文和 exact tools。 |
+| async local | 显式 async、Coordinator worker、或自动后台条件满足 | 返回 `async_launched`，完成后注入 `<task-notification>`。 |
+| sync local | 默认前台一次性 subagent | 当前 tool call 返回 `tool_result`。 |
+
+所以文档里不能把“Agent”写成一个单一概念：同一个工具入口下面至少有五条运行路径。
+
+## 通信路径对照
+
+多 Agent 的通信路径决定了结果是否进入当前 turn、是否持久化、能不能 resume。
+
+| 通信路径 | 发送者 | 接收者 | 用途 | 持久化/恢复 |
+|---|---|---|---|---|
+| `tool_result` | sync subagent | 当前 assistant turn | 一次性前台结果 | 写入主 transcript。 |
+| `<task-notification>` | async local agent / coordinator worker | 主线程下一 turn | 后台完成/失败/被杀通知 | 来自 `LocalAgentTask` lifecycle 和 sidechain。 |
+| `SendMessage(to: agentId)` | Coordinator 或用户 | local agent task | 继续 running/stopped worker | running 时排队；stopped 时尝试 sidechain resume。 |
+| `SendMessage(to: teammateName)` | lead / teammate | teammate mailbox | Swarm 普通通信 | 写 inbox JSON，按 name 寻址。 |
+| `SendMessage(to: "*")` | lead / teammate | team members | Swarm broadcast | 写多个 inbox；structured message 不能 broadcast。 |
+| structured mailbox protocol | lead / teammate / runtime | 特定 teammate 或 lead | permission、plan、shutdown、mode、task assignment | 保持 unread 给 poller 路由，不应被普通 attachment 吞掉。 |
+| CCR events / polling | remote runtime | `RemoteAgentTask` | remote agent 状态和结果 | 本地 sidecar + 远端 session 状态。 |
+
+### SendMessage 路由
+
+```mermaid
+flowchart TD
+  A["SendMessage(to)"] --> B{"cross-session scheme?"}
+  B -->|yes| C["UDS / LAN / bridge plain text"]
+  B -->|no| D{"matches LocalAgentTask?"}
+  D -->|running| E["queuePendingMessage"]
+  D -->|stopped or evicted| F["resumeAgentBackground from sidechain"]
+  D -->|no| G{"to == * ?"}
+  G -->|yes| H["broadcast team mailbox"]
+  G -->|no| I{"structured protocol?"}
+  I -->|yes| J["write protocol message"]
+  I -->|no| K["write teammate mailbox"]
+```
+
+plain text `SendMessage` 要带 `summary`。structured message 不能 broadcast，也不能跨 `uds/bridge/tcp` session。单 session 下 teammate name 是裸 name，`to` 不应写成含 `@` 的跨域地址。
+
+## Mailbox 协议表
+
+Mailbox 路径是：
+
+```text
+~/.claude/teams/<team-name>/inboxes/<agent-name>.json
+```
+
+它有 lock、原子 rename、大小上限和压缩策略：
+
+| 限制 | 值 |
+|---|---|
+| 单条 text | 64KB |
+| mailbox 文件 | 4MB |
+| retained bytes | 2MB |
+| 普通 message 保留 | 最多 1000 条 |
+| read message 保留 | 最多 200 条 |
+| unread protocol message 保留 | 最多 2000 条 |
+
+协议消息不只是“聊天”：
+
+| 消息类型 | 典型发送者 | 典型接收者 | 消费者 | 是否应进入普通 LLM context |
+|---|---|---|---|---|
+| plain text | lead / teammate | teammate / lead | mailbox attachment 或 prompt handler | 是 |
+| broadcast | lead / teammate | team members | mailbox attachment 或 prompt handler | 是 |
+| `task_assignment` | `TaskUpdate` | new owner | teammate poller / runner | 通常作为任务触发，不应当成普通闲聊 |
+| `permission_request/response` | teammate / lead | lead / teammate | `useInboxPoller` + permission UI queue | 否 |
+| `sandbox_permission_request/response` | teammate / sandbox host | lead / teammate | permission sync | 否 |
+| `plan_approval_request/response` | teammate / lead | lead / teammate | plan approval path | 否 |
+| `shutdown_request/approved/rejected` | lead / teammate | teammate / lead | backend / runner / poller | 否 |
+| `mode_set_request` | lead | teammate | permission mode sync | 否 |
+| `team_permission_update` | lead | team members | permission sync | 否 |
+| idle notification | teammate runner | lead | UI / lead poller | 通常否 |
+
+一个重要边界：mailbox attachment 只消费非结构化消息；结构化协议消息应保持 unread，交给 `useInboxPoller` 或 in-process runner 路由。否则权限、plan、shutdown 可能被当成普通上下文吞掉。
+
+## Task 不是 Runtime Task
+
+`TaskCreate` 的 task 和 `LocalAgentTask` 的 task 是两套模型。
+
+| 名称 | 源码类型 | 存储 | 状态 | 谁消费 |
+|---|---|---|---|---|
+| work item task | `src/utils/tasks.ts` 的 `Task` | `~/.claude/tasks/<taskListId>/<id>.json` | `pending/in_progress/completed` | Task tools、TaskList UI、teammate 认领 |
+| runtime task | `TaskStateBase` 子类型 | `AppState.tasks`，部分有 sidecar/output | `running/completed/failed/killed` 等 | UI、spinner、background selector、kill/resume |
+
+共享任务生命周期：
+
+```mermaid
+flowchart TD
+  A["TaskCreate"] --> B["pending task JSON"]
+  B --> C["TaskList"]
+  C --> D["Teammate chooses work"]
+  D --> E["TaskUpdate status=in_progress owner=me"]
+  E --> F["execute work"]
+  F --> G["TaskUpdate status=completed"]
+  G --> H["TaskCompleted hooks"]
+  G --> I["tool_result hints: call TaskList for next task"]
+```
+
+`TaskUpdate` 在 Swarm 下有增强：
+
+| 行为 | 说明 |
+|---|---|
+| teammate 标记 `in_progress` 且 owner 为空 | 自动把 owner 设为当前 teammate name。 |
+| owner 变化 | 写 `task_assignment` 到新 owner mailbox。 |
+| status -> `completed` | 执行 TaskCompleted hooks。 |
+| teammate 完成任务 | tool result 追加提示：立刻 `TaskList` 找下一项。 |
+| 主线程完成 3+ 任务且没有 verification | 在 feature gate 下追加 verification nudge。 |
+
+runtime task 类型包括：
+
+| 类型 | 运行位置 | 典型场景 |
+|---|---|---|
+| `LocalAgentTask` | 本地子 agent | 普通后台 agent、fork、coordinator worker。 |
+| `InProcessTeammateTask` | 同进程 runner | in-process teammate。 |
+| `RemoteAgentTask` | CCR remote session | remote agent。 |
+| `LocalShellTask` | 本地 shell | 后台 shell。 |
+| `LocalWorkflowTask` | 本地 workflow | workflow 编排。 |
+| `DreamTask` | 后台静默 | memory dream。 |
+| `MonitorMcpTask` | 本地监控 | MCP monitor。 |
+
+## 持久化与恢复矩阵
+
+恢复能力取决于状态放在哪里。最重要的区别是：能看到状态不等于能继续运行。
+
+| 机制 | 持久化 | resume 后能看到 | resume 后能继续跑 | 边界 |
+|---|---|---|---|---|
+| main session | 主 session JSONL | 对话链、metadata、mode | 是，按主会话恢复 | 受 compact/branch/leaf 影响。 |
+| coordinator mode | 主 session JSONL 的 `mode` entry | 当前会话模式 | 是，`matchSessionMode()` 会切 env | prompt/tool 状态仍受当前启动参数影响。 |
+| coordinator worker | local agent sidechain + `.meta.json` | agent task 身份和历史 | 通常可 `resumeAgentBackground()` | 缺 sidechain/meta 或工具定义变化会失败。 |
+| ordinary/fork subagent | local agent sidechain + `.meta.json` | agent 历史 | 可恢复，fork 依赖 `agentType:"fork"` | fork 恢复需要 metadata 正确。 |
+| remote agent | `remote-agents/remote-agent-<taskId>.meta.json` + CCR | remote task 镜像 | 取决于 CCR session 状态 | 404/archive 会删除 sidecar。 |
+| team config | `~/.claude/teams/<team>/config.json` | team/member roster | 不代表 teammate runner 还活 | `TeamFile` 是事实源，`AppState` 是投影。 |
+| mailbox | `~/.claude/teams/<team>/inboxes/*.json` | 未读普通/协议消息 | 可继续投递 | structured message 需要 poller/runner 正确消费。 |
+| shared tasks | `~/.claude/tasks/<team>/*.json` | task list / owner / status | 可继续认领/更新 | owner 可能指向已经不活跃的 teammate。 |
+| in-process teammate runner | leader 进程内存 | 不能完整看到 runner 内态 | 不能完整跨进程恢复 | AbortController、pending queue、recent messages 都在内存。 |
+| pane-based teammate | 外部 pane + transcript + team file | 可能仍可见 | best-effort | leader 侧 backend map 不持久化，active/kill 依赖 pane 状态。 |
+
+调试时可以按这个顺序问：
+
+1. 文件还在吗？
+2. `AppState` 投影还在吗？
+3. runtime task 还在 `running` 吗？
+4. 通信通道还可用吗？
+5. sidechain / inbox / remote sidecar 是否足够恢复？
+
+## 用户可见状态如何投影
+
+UI 展示的是不同状态源的投影，不是单一真相。
+
+| UI | 数据源 | 能说明什么 | 不能说明什么 |
+|---|---|---|---|
+| TaskListV2 | task files + `teamContext` | work item task、owner、状态 | owner 对应 teammate 一定还活。 |
+| TeammateSpinnerTree | running in-process teammates | 当前 leader 进程内的 teammate 活动 | pane-based teammate 或历史 teammate 全部状态。 |
+| TeammateSpinnerLine | `InProcessTeammateTaskState` | idle、approval、stopping、tool/token、最近消息 | 完整 transcript。 |
+| BackgroundAgentSelector | backgrounded `LocalAgentTask` | 可选择的本地后台 agent | remote/shell/workflow/in-process teammate。 |
+| agent transcript view | `viewingAgentTaskId` | local agent 或 in-process teammate 的可视化对话 | pane teammate 的完整外部进程状态。 |
+| TeamsDialog / TeamStatus | `AppState.teamContext` + team file | 团队成员展示、管理、kill/shutdown/mode | runner 一定可恢复。 |
+
+pane-based team 主要通过 footer TeamStatus 和 TeamsDialog 管理：Enter 查看，`k` kill，`s` shutdown，`p` prune idle，Shift+Tab 切 permission mode。in-process teammate 的 transcript view 输入会进 `pendingUserMessages`，不是写 mailbox。
+
+## 两条端到端场景
+
+### 复杂 bug 用 Coordinator
+
+| 步骤 | 发生了什么 | 运行体 | 通信 | 持久化 |
+|---|---|---|---|---|
+| 1 | 用户提出复杂 bug | 主会话 | user message | main JSONL |
+| 2 | Coordinator 拆成调查、实现、验证 | Coordinator 主线程 | `Agent(worker)` | main JSONL + task state |
+| 3 | worker 异步执行 | `LocalAgentTask` | tool calls | sidechain JSONL |
+| 4 | worker 完成 | `LocalAgentTask` | `<task-notification>` | notification queue / main turn |
+| 5 | Coordinator 综合 root cause | 主线程 | assistant reasoning | main JSONL |
+| 6 | 需要修正方向 | 同一个或新 worker | `SendMessage(to: agentId, summary, message)` 或 fresh `Agent` | sidechain / new sidechain |
+| 7 | 汇总给用户 | 主线程 | assistant message | main JSONL |
+
+这个流程没有 `TeamCreate`，也不依赖 shared task list。
+
+### 长期并行任务用 Swarm
+
+| 步骤 | 发生了什么 | 状态源 | 通信 |
+|---|---|---|---|
+| 1 | `TeamCreate({ team_name })` | `teams/<team>/config.json` + `tasks/<team>` | tool result |
+| 2 | `TaskCreate` 多个工作项 | task JSON | Task tools |
+| 3 | `Agent({ name: "researcher" })` | TeamFile member + backend task/pane | initial prompt |
+| 4 | teammate 认领任务 | task JSON owner/status | `TaskUpdate` |
+| 5 | lead 发消息 | inbox JSON | `SendMessage(to: teammateName)` |
+| 6 | teammate 完成一轮 | runner/poller 状态 | idle notification |
+| 7 | teammate 继续领任务 | task list | `TaskList` / claim |
+| 8 | `TeamDelete({ wait_ms })` | team/task dirs cleanup | shutdown request / response |
+
+这个流程里 team、task list 和 mailbox 是核心。teammate 输出不会自动给 lead；需要 `SendMessage` 或明确的协议消息。
+
+## 失败与排障矩阵
+
+| 现象 | 先查什么 | 常见原因 | 处理 |
+|---|---|---|---|
+| Coordinator worker 结果没回来 | `AppState.tasks[agentId]`、notification queue、sidechain | worker 仍 running、failed、被 killed、notification 尚未进入下一 turn | 等下一 turn；或看 sidechain / task status。 |
+| `SendMessage(to: agentId)` 找不到 worker | agentId/name、sidechain `.jsonl/.meta.json` | agent 被 evict、metadata 缺失、传了 teammate name | 用正确 raw agentId；必要时新开 worker。 |
+| `SendMessage(to: teammate)` 失败 | teamContext、team file、inbox path | teammate name 拼错、当前 session 无 team、用了含 `@` 地址 | 用当前 team 内裸 teammate name。 |
+| plain text `SendMessage` 校验失败 | 参数 | 缺 `summary` | 补 `summary`。 |
+| structured message 没生效 | inbox read 状态、poller | 被当普通 attachment 标 read，或 consumer 没跑 | 确认 structured message 保持 unread，poller/runner 活着。 |
+| 任务不显示 | `leaderTeamName`、`getTaskListId()`、tasks dir | lead/teammate 指向不同 task list | 查 env/teamName/sessionId 优先级。 |
+| task 被认领但没人执行 | task owner、team member active、runner/pane | owner teammate 不活跃或 runner 丢失 | 重新分配 owner，或重启 teammate。 |
+| TeamDelete 拒绝清理 | `TeamFile.members[].isActive` | 仍有 active teammate | 先 graceful shutdown，或确认后手动清理。 |
+| resume 后 team 在但 teammate 不跑 | team file、runner/pane 状态 | in-process runner 在旧进程内，不能恢复 | 重新 spawn teammate 或用现有 mailbox/task 重新编排。 |
+| pane teammate 似乎还在但 UI 不准 | paneId、backendType、backend map | leader 侧 `spawnedTeammates` map 不持久化 | 以 TeamFile + pane 实际状态为准，best-effort 管理。 |
+| permission/plan 卡住 | leader inbox、permission UI queue、protocol response | leader poller 没消费，或 response 没写回 | 查 `useInboxPoller` 和对应 inbox。 |
+| remote agent resume 失败 | remote sidecar、CCR session | session 404 / archived | 接受 sidecar 清理，重新创建 remote agent。 |
+
+## 常见误区
+
+| 误区 | 正确理解 |
+|---|---|
+| Coordinator 就是 Swarm 的 Team Lead | 不是。Coordinator worker 是 async subagent，不是 teammate。 |
+| Swarm 必须设置 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | 当前实现默认启用；用 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS_DISABLED` 关闭。 |
+| `TaskCreate` 创建了一个运行中的 agent | 它只创建 work item JSON；运行体是 `LocalAgentTask` / `InProcessTeammateTask` 等。 |
+| teammate 完成一轮后结果自动给 lead | 不一定。teammate 需要通过 `SendMessage` 沟通；runner 也会发送 idle notification。 |
+| mailbox 按 agentId 寻址 | Swarm mailbox 按 teammate name 寻址。 |
+| BackgroundAgentSelector 会列出所有后台任务 | 它只列 backgrounded `LocalAgentTask`，不列 remote/shell/workflow/in-process teammate。 |
+| `TeamUpdate` 是一个工具 | 当前源码没有独立 `TeamUpdateTool`；团队成员更新分散在 spawn、teamHelpers、dialogs 中。 |
+| `SyntheticOutput` 是 Swarm 内部通信工具 | 它主要用于结构化输出，不是 Team 协作核心。 |
+| shutdown request 是强杀 | 不是，它是模型处理的 graceful shutdown 协议。 |
+| in-process teammate 可以像 local agent 一样跨进程 resume | 不行，runner 运行态在内存中，进程重启后不能完整恢复。 |
+
+## 延伸阅读
+
+这篇文档是跨机制总览。需要深入某条链路时，优先看专题文档：
+
+| 想深入 | 阅读 |
+|---|---|
+| `AgentTool` 参数、sync/async/fork、通知队列 | `docs/agent/sub-agents.mdx` |
+| Task V2 数据模型、锁、高水位、owner、hooks | `docs/tools/task-management.mdx` |
+| JSONL transcript、sidechain、compact、resume、remote sidecar | `docs/internals/session-transcript-persistence.md` |
+| Coordinator feature 的单独说明 | `docs/features/coordinator-mode.md` |
+| worktree 隔离 | `docs/agent/worktree-isolation.mdx` |
+
+## 源码入口索引
+
+| 问题 | 从这里看 |
+|---|---|
+| coordinator mode 检测、恢复、prompt、context | `src/coordinator/coordinatorMode.ts` |
+| `/coordinator` 命令 | `src/commands/coordinator.ts` |
+| coordinator worker 定义 | `src/coordinator/workerAgent.ts` |
+| system prompt 选择 | `src/utils/systemPrompt.ts` |
+| coordinator 工具过滤 | `src/utils/toolPool.ts` |
+| coordinator mode 持久化 | `src/utils/sessionStorage.ts` 的 `mode` entry / `saveMode()` |
+| AgentTool 路由 | `packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx` |
+| subagent query loop | `packages/builtin-tools/src/tools/AgentTool/runAgent.ts` |
+| async local agent lifecycle | `packages/builtin-tools/src/tools/AgentTool/agentToolUtils.ts` |
+| local agent runtime task | `src/tasks/LocalAgentTask/LocalAgentTask.tsx` |
+| remote agent runtime task | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` |
+| agent resume | `packages/builtin-tools/src/tools/AgentTool/resumeAgent.ts` |
+| task stop | `packages/builtin-tools/src/tools/TaskStopTool/TaskStopTool.ts`、`src/tasks/stopTask.ts` |
+| team gate | `src/utils/agentSwarmsEnabled.ts` |
+| team file helpers | `src/utils/swarm/teamHelpers.ts` |
+| TeamCreate | `packages/builtin-tools/src/tools/TeamCreateTool/TeamCreateTool.ts` |
+| TeamDelete | `packages/builtin-tools/src/tools/TeamDeleteTool/TeamDeleteTool.ts` |
+| spawn teammate | `packages/builtin-tools/src/tools/shared/spawnMultiAgent.ts` |
+| in-process teammate spawn | `src/utils/swarm/spawnInProcess.ts` |
+| in-process teammate runner | `src/utils/swarm/inProcessRunner.ts` |
+| pane backend | `src/utils/swarm/backends/PaneBackendExecutor.ts` |
+| teammate AsyncLocalStorage identity | `src/utils/teammateContext.ts` |
+| mailbox | `src/utils/teammateMailbox.ts` |
+| permission sync | `src/utils/swarm/permissionSync.ts` |
+| SendMessage routing | `packages/builtin-tools/src/tools/SendMessageTool/SendMessageTool.ts` |
+| shared task list | `src/utils/tasks.ts` |
+| Task tools | `packages/builtin-tools/src/tools/TaskCreateTool`、`TaskUpdateTool`、`TaskListTool`、`TaskGetTool` |
+| inbox polling | `src/hooks/useInboxPoller.ts` |
+| swarm initialization | `src/hooks/useSwarmInitialization.ts` |
+| teammate view | `src/state/teammateViewHelpers.ts`、`src/screens/REPL.tsx` |
+| teammate spinner | `src/components/Spinner/TeammateSpinnerTree.tsx`、`TeammateSpinnerLine.tsx` |
+| team dialog/status | `src/components/teams/TeamsDialog.tsx`、`src/components/teams/TeamStatus.tsx` |
+| background local agent selector | `src/hooks/useBackgroundAgentTasks.ts`、`src/components/tasks/BackgroundAgentSelector.tsx` |

docs/conversation/multi-turn.mdx

@@ -7,6 +7,322 @@ sourceRef: "3ec5675 (2026-04-08)"
 
 {/* 本章目标：从源码角度揭示会话编排、持久化存储、成本追踪和模型切换的完整链路 */}
 
+首先要区分claude code的多种交互方式
+
+REPL关注交互形态，SDK关注接入方式，ACP则关注通信协议。
+
+### 🆚 核心概念对比
+
+| 维度 | 🖥️ REPL (交互形态) | 🧩 SDK (接入方式) | 🌉 ACP (通信协议) |
+| :--- | :--- | :--- | :--- |
+| **是什么** | 供开发者直接在终端使用的**交互式对话环境** | 面向开发者的**程序化调用库**，供集成到其他应用 | 一种**开放式的通信标准**，连接不同AI Agent与编辑器 |
+| **使用方式** | 1. 直接在终端输入`claude`命令<br>2. 进入专用界面（基于React Ink渲染）<br>3. 通过斜杠命令（如`/help`）交互 | 1. 在自己的Node.js/Python项目中安装SDK包（如`npm install claude-code-sdk`）<br>2. 通过API发送查询 | 1. 通过ACP适配器（如`claude-code-acp`）启动Claude Code<br>2. 供编辑器通过ACP协议与其通信 |
+| **典型场景** | 开发者日常编写代码时，随时向其提问、修改代码或执行任务 | 将Claude Code的核心能力（对话、工具执行等）集成到自动化脚本、CI/CD流程或其他应用的后台中 | 将Claude Code的能力集成到JetBrains IDE、Zed等第三方编辑器中，利用其UI交互功能 |
+| **主要特点** | - **面向人**：交互式、直观<br>- **功能完整**：可使用所有内置工具，并支持MCP集成<br>- **处理复杂任务**：可自主规划、执行多步操作 | - **面向程序**：编程化、可集成<br>- **轻量级**：不依赖Claude Code的完整运行时<br>- **由你控制**：适合在自有应用中实现自动化 | - **标准化**：统一不同Agent与编辑器间的通信<br>- **双向通信**：Agent可主动向编辑器请求文件、执行命令等<br>- **与编辑器深度整合**：能完全复用Claude Code的能力 |
+
+其中的 🧩 SDK (接入方式) 与 🌉 ACP (通信协议)采用如下QueryEngine实现会话管理
+
+作为一个对话终端（🖥️ REPL 交互形态模式），则使用的是 onQueryImpl 在 src/screens/REPL.tsx 中调用 query() 函数
+
+对于REPL 交互形态模式的调用链路如下
+```
+用户输入  
+  ↓  
+onSubmit (REPL.tsx)  
+  ↓  
+handlePromptSubmit (handlePromptSubmit.ts)  
+  ↓  
+executeUserInput (handlePromptSubmit.ts)  
+  ↓  
+onQuery (REPL.tsx)  
+  ↓  
+onQueryImpl (REPL.tsx)  
+  ↓  
+query (query.ts) ← 在这里调用  
+```
+
+其中
+
+query 函数是 Agentic Loop 的核心实现，包含 while(true) 循环处理对话回合 query.ts:460-522
+
+onQueryImpl 是 REPL（Read-Eval-Print Loop）中与 AI 模型交互的核心控制器，它负责：
+
+1.环境准备（IDE、诊断、权限）
+
+2.会话标题的首次生成
+
+3.构建动态系统提示和用户上下文
+
+4.执行流式查询并实时更新 UI
+
+5.收集性能指标和最终清理
+
+##  `onQueryImpl` 方法的详细解析
+以下是对 `onQueryImpl` 方法的详细解析。该方法是一个 React `useCallback` 包装的异步函数，负责处理用户消息到 AI 模型（Claude）的**完整查询流程**，包括预处理、系统提示构建、工具上下文准备、流式查询执行、后处理与指标记录。
+
+---
+
+### 一、函数签名与参数
+
+```typescript
+const onQueryImpl = useCallback(
+  async (
+    messagesIncludingNewMessages: MessageType[],
+    newMessages: MessageType[],
+    abortController: AbortController,
+    shouldQuery: boolean,
+    additionalAllowedTools: string[],
+    mainLoopModelParam: string,
+    effort?: EffortValue,
+  ) => { ... },
+  [ ...dependencies ]
+)
+```
+
+| 参数                             | 说明                                                                                     |
+| -------------------------------- | ---------------------------------------------------------------------------------------- |
+| `messagesIncludingNewMessages` | 包含新增消息的完整消息列表，用于构建模型输入                                             |
+| `newMessages`                  | 本次新增的消息（例如用户刚输入的文本或附件）                                             |
+| `abortController`              | 用于取消当前查询的控制器                                                                 |
+| `shouldQuery`                  | 是否真正执行查询；若为 `false` 则跳过模型调用（例如处理无效斜杠命令、手动 compact 等） |
+| `additionalAllowedTools`       | 本轮查询额外允许的工具列表（通常来自 Skill 的 frontmatter）                              |
+| `mainLoopModelParam`           | 指定本次使用的主模型参数（如 `'claude-3-opus'`）                                       |
+| `effort`                       | 可选，覆盖全局的“努力程度”值（用于控制模型推理深度）                                   |
+
+---
+
+### 二、总体执行流程
+
+下图概括了函数的主要分支与关键步骤：
+
+```mermaid
+graph TD
+A["开始"] --> B{shouldQuery?}
+B -- true --> C["IDE集成：刷新MCP客户端，诊断追踪，关闭差异视图"]
+B -- false --> D["仅处理compact边界/重置状态并返回"]
+C --> E["标记项目onboarding完成"]
+E --> F["尝试生成会话标题（仅一次）"]
+F --> G["将additionalAllowedTools写入全局权限store"]
+G --> H["获取ToolUseContext（含最新工具/MCP）"]
+H --> I["如有effort，临时覆盖getAppState中的effortValue"]
+I --> J["并行执行：系统提示/用户上下文/系统上下文/自动模式检查"]
+J --> K["构建有效系统提示"]
+K --> L["重置各类耗时计时器"]
+L --> M["执行query生成器，流式处理事件"]
+M --> N["若BUDDY开启，触发companion观察者"]
+N --> O["若UDS_INBOX且中断，记录错误"]
+O --> P["ant用户：收集API指标并插入指标消息"]
+P --> Q["重置加载状态，输出性能报告，调用onTurnComplete"]
+Q --> R["结束"]
+D --> R
+```
+
+---
+
+### 三、核心逻辑详解
+
+#### 3.1 IDE 集成与诊断（仅 `shouldQuery = true`）
+
+```typescript
+const freshClients = mergeClients(initialMcpClients, store.getState().mcp.clients);
+diagnosticTracker.handleQueryStart(freshClients);
+const ideClient = getConnectedIdeClient(freshClients);
+if (ideClient) closeOpenDiffs(ideClient);
+```
+
+- 从 store 中获取最新的 MCP 客户端（因为 `useManageMCPConnections` 可能在闭包捕获后更新了状态）。
+- 通知诊断追踪器查询开始。
+- 若存在已连接的 IDE 客户端，关闭所有打开的差异视图（清理环境）。
+
+#### 3.2 会话标题生成（仅一次）
+
+```typescript
+if (!titleDisabled && !sessionTitle && !agentTitle && !haikuTitleAttemptedRef.current) {
+  const firstUserMessage = newMessages.find(m => m.type === 'user' && !m.isMeta);
+  const text = getContentText(firstUserMessage.message.content);
+  if (text && !text.startsWith(`<${LOCAL_COMMAND_STDOUT_TAG}>`) ... ) {
+    haikuTitleAttemptedRef.current = true;
+    generateSessionTitle(text, ...).then(title => setHaikuTitle(title));
+  }
+}
+```
+
+- 仅当全局标题未禁用、当前无任何标题且从未尝试过时执行。
+- 从新增消息中提取第一条**非元用户消息**的真实文本。
+- 跳过合成面包屑（如 slash 命令输出、skill 扩展标记等）。
+- 异步调用 `generateSessionTitle`，结果通过 `setHaikuTitle` 保存；失败则重置 ref 允许重试。
+
+#### 3.3 权限工具覆盖写入 Store
+
+```typescript
+store.setState(prev => {
+  const cur = prev.toolPermissionContext.alwaysAllowRules.command;
+  if (cur === additionalAllowedTools || (cur?.length === ...)) return prev;
+  return { ...prev, toolPermissionContext: { ...prev.toolPermissionContext, alwaysAllowRules: { ...prev.toolPermissionContext.alwaysAllowRules, command: additionalAllowedTools } } };
+});
+```
+
+- 将本轮 `additionalAllowedTools` 写入全局 store 的 `toolPermissionContext.alwaysAllowRules.command`。
+- 用于限定本轮查询中可用的工具集（例如 Skill 专属工具）。
+- 通过浅比较避免不必要的状态更新。
+- 即使在 `shouldQuery=false` 时也会执行（例如 forked 命令需要此权限信息），但原代码位置在 `shouldQuery` 分支**之前**，所以始终会更新。
+
+#### 3.4 `shouldQuery = false` 分支
+
+```typescript
+if (!shouldQuery) {
+  if (newMessages.some(isCompactBoundaryMessage)) {
+    setConversationId(randomUUID());
+    if (feature('PROACTIVE') || feature('KAIROS')) proactiveModule?.setContextBlocked(false);
+  }
+  resetLoadingState();
+  setAbortController(null);
+  return;
+}
+```
+
+- 处理不需要实际调用模型的情况（如用户输入了无效斜杠命令，或者手动 `/compact` 等）。
+- 若新消息中包含 **compact 边界消息**（压缩边界），则：
+  - 生成新的 `conversationId`，促使 UI 中消息行组件重新挂载。
+  - 若开启了 PROACTIVE/KAIROS 特性，清除上下文阻塞标志（恢复主动提示）。
+- 最后重置加载状态并清空 abortController。
+
+#### 3.5 查询前置准备（`shouldQuery = true`）
+
+##### 3.5.1 获取 ToolUseContext
+
+```typescript
+const toolUseContext = getToolUseContext(messagesIncludingNewMessages, newMessages, abortController, mainLoopModelParam);
+const { tools: freshTools, mcpClients: freshMcpClients } = toolUseContext.options;
+```
+
+- `getToolUseContext` 内部会从 store 中读取最新的 tools 和 MCP 客户端配置，确保闭包捕获的旧值不会导致遗漏新连接的工具或 MCP 服务器。
+
+##### 3.5.2 Effort 覆盖（临时）
+
+```typescript
+if (effort !== undefined) {
+  const previousGetAppState = toolUseContext.getAppState;
+  toolUseContext.getAppState = () => ({ ...previousGetAppState(), effortValue: effort });
+}
+```
+
+- 如果传入了 `effort` 参数，临时覆盖 `getAppState` 返回的 `effortValue`。
+- 作用域**仅限于本轮查询**，不影响全局 store，避免后台 Agent 或 UI 组件误读到该临时值。
+
+##### 3.5.3 并行获取提示与上下文
+
+```typescript
+const [, , defaultSystemPrompt, baseUserContext, systemContext] = await Promise.all([
+  undefined,
+  feature('TRANSCRIPT_CLASSIFIER') ? checkAndDisableAutoModeIfNeeded(...) : undefined,
+  getSystemPrompt(freshTools, mainLoopModelParam, additionalWorkingDirectories, freshMcpClients),
+  getUserContext(),
+  getSystemContext(),
+]);
+```
+
+- 并行执行以下任务以节省时间：
+  - **自动模式断路器**：如果启用了转录分类器，检查并可能禁用快速模式（`fastMode`）。
+  - **系统提示**：基于最新工具、模型参数、额外工作目录、MCP 客户端生成。
+  - **用户上下文**：如当前工作区、环境变量等。
+  - **系统上下文**：如操作系统、终端信息等。
+
+##### 3.5.4 增强用户上下文
+
+```typescript
+const userContext = {
+  ...baseUserContext,
+  ...getCoordinatorUserContext(freshMcpClients, getScratchpadDir()),
+  ...((feature('PROACTIVE') || feature('KAIROS')) && proactiveModule?.isProactiveActive() && !terminalFocusRef.current
+    ? { terminalFocus: 'The terminal is unfocused — the user is not actively watching.' }
+    : {}),
+};
+```
+
+- 合并基本用户上下文、协调器上下文（与 MCP 协作相关）、以及可选的终端焦点状态（当 proactive 特性激活且终端未聚焦时，提示模型用户未在观看）。
+
+##### 3.5.5 构建最终系统提示
+
+```typescript
+const systemPrompt = buildEffectiveSystemPrompt({
+  mainThreadAgentDefinition,
+  toolUseContext,
+  customSystemPrompt,
+  defaultSystemPrompt,
+  appendSystemPrompt,
+});
+```
+
+- 整合主线程 Agent 定义、工具上下文、自定义系统提示、默认系统提示以及需要追加的内容。
+
+#### 3.6 执行查询与流式事件处理
+
+```typescript
+resetTurnHookDuration(); resetTurnToolDuration(); resetTurnClassifierDuration();
+for await (const event of query({ messages, systemPrompt, userContext, systemContext, canUseTool, toolUseContext, querySource })) {
+  onQueryEvent(event);
+}
+```
+
+- 重置本轮钩子、工具、分类器的耗时计时器。
+- 调用 `query` 生成器函数（负责与模型 API 通信并返回 SSE 事件流）。
+- 遍历每个事件并调用 `onQueryEvent`（通常用于更新 UI 消息列表、处理工具调用等）。
+
+#### 3.7 后处理与指标收集
+
+##### 3.7.1 BUDDY 特性（companion 反应）
+
+```typescript
+if (feature('BUDDY') && typeof fireCompanionObserver === 'function') {
+  fireCompanionObserver(messagesRef.current, reaction => setAppState(prev => ({ ...prev, companionReaction: reaction })));
+}
+```
+
+- 将当前消息列表传递给 companion 观察者，并根据返回的反应更新全局状态。
+
+##### 3.7.2 UDS_INBOX 中断处理
+
+```typescript
+if (feature('UDS_INBOX') && abortController.signal.aborted) {
+  pipeReturnHadErrorRef.current = true;
+  relayPipeMessage({ type: 'error', data: 'Slave request was interrupted before completion.' });
+}
+```
+
+- 若因中断导致查询未完成，标记错误并通过管道中继消息。
+
+##### 3.7.3 Ant 内部用户的 API 指标记录
+
+```typescript
+if (process.env.USER_TYPE === 'ant' && apiMetricsRef.current.length > 0) {
+  const entries = apiMetricsRef.current;
+  const ttfts = entries.map(e => e.ttftMs);
+  const otpsValues = entries.map(e => { /* 计算每请求的 OTPs */ });
+  const isMultiRequest = entries.length > 1;
+  // 创建 API 指标消息并添加到消息列表
+  setMessages(prev => [...prev, createApiMetricsMessage({ ttftMs: isMultiRequest ? median(ttfts) : ttfts[0], ... })]);
+}
+```
+
+- 仅当用户类型为 `'ant'` 且存在 API 指标记录时执行。
+- 收集每次请求的 **首字节时间 (TTFT)** 和 **每秒输出 Token 数 (OTPS)**。
+- 若本轮包含多次请求（例如工具调用循环），计算中位数（P50）后存入指标消息。
+- 同时记录钩子耗时、工具耗时、分类器耗时、本轮总时长、配置写入次数等。
+
+##### 3.7.4 重置与清理
+
+```typescript
+resetLoadingState();
+logQueryProfileReport();
+await onTurnComplete?.(messagesRef.current);
+```
+
+- 重置加载状态（隐藏 loading 指示器）。
+- 输出查询性能报告（如果调试标志启用）。
+- 调用外部传入的 `onTurnComplete` 回调，并传递完整消息列表（通常用于触发后续行为如自动滚动、保存会话等）。
+
+
 ## 单轮 vs 多轮：架构层面的差异
 
 - **单轮**（一次 Agentic Loop）：`query()` 函数的一次完整执行——组装上下文 → 调 API → 处理工具调用 → 循环直到结束
@@ -28,7 +344,7 @@ QueryEngine 内部状态（src/QueryEngine.ts 构造函数）
 
 ## QueryEngine 的核心方法：submitMessage()
 
-每次用户输入一条消息，REPL 或 SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
+每次用户输入一条消息，SDK 调用 `submitMessage()`，它会执行完整的 turn 初始化链路：
 
 ```typescript
 // src/QueryEngine.ts — QueryEngine.submitMessage() 简化流程

docs/internals/session-transcript-persistence.md

@@ -0,0 +1,828 @@
+# JSONL Transcript 会话持久化与恢复机制
+
+本文梳理 Claude Code 基于 JSONL transcript 的会话持久化、恢复、错误恢复、上下文压缩、分支、subagent、fork agent 和 remote agent 逻辑。
+
+这不是按文件罗列的源码笔记，而是一份机制手册：先建立心智模型，再看数据结构、生命周期、异常路径和源码入口。
+
+## 怎么读
+
+| 如果你想看 | 建议先读 |
+|---|---|
+| 为什么 resume 能恢复到正确位置 | `总览`、`读取与链路重建`、`恢复入口` |
+| 为什么 compact 后历史还在但模型看不到 | `上下文视图`、`Compact 与投影` |
+| 为什么 subagent 不污染主会话 | `存储拓扑`、`Subagent 与 Fork Agent` |
+| `/branch`、`--fork-session`、`/fork` 有什么区别 | `分支与 Fork 对比` |
+| 崩溃、超限、取消后如何恢复 | `错误恢复矩阵` |
+
+## 总览
+
+Claude Code 的本地会话核心是 append-only JSONL。每一行是一个 `Entry`，但恢复时不会按文件顺序重放整个文件，而是：
+
+1. 把 transcript message 放入 `uuid -> message` map。
+2. 把 metadata entry 放入各自 map 或数组。
+3. 选择最新 leaf。
+4. 从 leaf 沿 `parentUuid` 回溯，得到当前有效链。
+5. 应用 compact、snip、preserved segment、content replacement 等投影。
+6. 恢复 sessionId、worktree、mode、agent setting、任务状态等内存状态。
+
+核心不变量：
+
+| 不变量 | 含义 |
+|---|---|
+| JSONL 尽量 append-only | compact、branch、sidechain 都优先追加新 entry，不直接改旧历史。 |
+| `uuid/parentUuid` 决定世界线 | 文件顺序只说明写入顺序，真正恢复靠链路回溯。 |
+| metadata 不参与主链 | title、tag、worktree、content replacement 等通过 sessionId/messageId/agentId 合并。 |
+| compact 不删除历史 | 它追加 boundary，模型视图从最后一个 boundary 后开始。 |
+| subagent 是 sidechain | 子 agent 的完整对话在独立 JSONL，父会话只看到 Agent tool 的结果/通知。 |
+| remote agent 不是 sidechain | remote agent 本地只保存 sidecar 身份，执行状态来自 CCR。 |
+
+### 系统分层
+
+```mermaid
+flowchart TD
+  A[磁盘层<br/>append-only JSONL + sidecar metadata] --> B[链路层<br/>uuid / parentUuid / leaf]
+  B --> C[投影层<br/>compact / snip / tool_result budget / context-collapse]
+  C --> D[恢复层<br/>deserialize / interrupt detection / metadata restore]
+  D --> E[运行层<br/>REPL / QueryEngine / AgentTask / RemoteTask]
+```
+
+### 存储拓扑
+
+```text
+~/.claude/projects/<project-key>/
+  <sessionId>.jsonl
+  <sessionId>/
+    subagents/
+      agent-<agentId>.jsonl
+      agent-<agentId>.meta.json
+      <subdir>/
+        agent-<agentId>.jsonl
+        agent-<agentId>.meta.json
+    remote-agents/
+      remote-agent-<taskId>.meta.json
+```
+
+| 文件 | 生成函数 | 用途 |
+|---|---|---|
+| `<sessionId>.jsonl` | `getTranscriptPath()` | 主会话 transcript。 |
+| `subagents/agent-<agentId>.jsonl` | `getAgentTranscriptPath(agentId)` | 本地 subagent / fork agent sidechain。 |
+| `subagents/agent-<agentId>.meta.json` | `getAgentMetadataPath(agentId)` | agentType、worktreePath、description。 |
+| `remote-agents/remote-agent-<taskId>.meta.json` | `getRemoteAgentMetadataPath(taskId)` | remote CCR session 身份，用于恢复 polling。 |
+
+## 核心源码地图
+
+| 机制 | 主要文件 |
+|---|---|
+| Entry 类型 | `src/types/logs.ts` |
+| 路径、写入、读取、链路重建 | `src/utils/sessionStorage.ts` |
+| 大文件流式读取 | `src/utils/sessionStoragePortable.ts` |
+| CLI resume 加载和中断检测 | `src/utils/conversationRecovery.ts` |
+| session 切换和状态恢复 | `src/utils/sessionRestore.ts` |
+| SDK/headless query 写 transcript | `src/QueryEngine.ts` |
+| API query loop、compact、错误恢复 | `src/query.ts` |
+| compact 实现 | `src/services/compact/*` |
+| context-collapse stub 与持久化接口 | `src/services/contextCollapse/*` |
+| `/branch` | `src/commands/branch/branch.ts` |
+| `/fork` | `src/commands/fork/fork.tsx` |
+| AgentTool 和 subagent | `packages/builtin-tools/src/tools/AgentTool/*` |
+| 通用 forked side query | `src/utils/forkedAgent.ts` |
+| remote agent task | `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` |
+
+## 数据模型
+
+`Entry` 定义在 `src/types/logs.ts`，可以分为三大类。
+
+| 类别 | 典型 type | 是否进入 `parentUuid` 链 | key | 恢复用途 |
+|---|---|---:|---|---|
+| transcript message | `user`、`assistant`、`attachment`、`system` | 是 | `uuid` | 重建对话链、模型上下文、UI scrollback。 |
+| session metadata | `custom-title`、`tag`、`mode`、`worktree-state`、`pr-link`、`agent-setting` | 否 | `sessionId` | 恢复标题、标签、模式、worktree、PR、agent 设置。 |
+| message metadata | `file-history-snapshot`、`attribution-snapshot`、`summary` | 否 | `messageId` 或 `leafUuid` | 恢复文件历史、归因、摘要。 |
+| replacement metadata | `content-replacement` | 否 | `sessionId` + optional `agentId` | 恢复大 tool_result 的替换决策。 |
+| context-collapse metadata | `marble-origami-commit`、`marble-origami-snapshot` | 否 | `sessionId` | 预留 context-collapse 恢复接口；当前实现为 stub。 |
+| queue/task metadata | `queue-operation`、`task-summary`、`speculation-accept` | 否 | 各自字段 | 恢复队列、任务摘要、推测接受统计。 |
+
+### TranscriptMessage 字段
+
+真正参与链路的是 `TranscriptMessage`：
+
+| 字段 | 含义 |
+|---|---|
+| `uuid` | 当前消息 ID。 |
+| `parentUuid` | 链路父节点，恢复时沿它回溯。 |
+| `logicalParentUuid` | compact boundary 等断链场景保留逻辑父节点。 |
+| `sessionId` | 所属主 session。 |
+| `cwd` | 写入时工作目录。 |
+| `timestamp` | 写入时间。 |
+| `version` | CLI 版本。 |
+| `gitBranch` | 写入时 git 分支。 |
+| `isSidechain` | 是否是 subagent sidechain。 |
+| `agentId` | sidechain 所属 agent。 |
+| `teamName/agentName/agentColor` | swarm / teammate 展示元数据。 |
+
+### JSONL 示例
+
+主会话消息：
+
+```jsonl
+{"type":"user","uuid":"u1","parentUuid":null,"sessionId":"s1","isSidechain":false,"cwd":"D:\\vibe\\claude-code","message":{"role":"user","content":"修复测试"}}
+{"type":"assistant","uuid":"a1","parentUuid":"u1","sessionId":"s1","isSidechain":false,"message":{"role":"assistant","content":[{"type":"text","text":"我来检查。"}]}}
+```
+
+sidechain 消息：
+
+```jsonl
+{"type":"user","uuid":"u2","parentUuid":null,"sessionId":"s1","isSidechain":true,"agentId":"ag1","message":{"role":"user","content":"分析 compact 路径"}}
+```
+
+agent 的 `content-replacement`：
+
+```jsonl
+{"type":"content-replacement","sessionId":"s1","agentId":"ag1","replacements":[{"messageUuid":"u2","toolUseId":"toolu_...","blockIndex":0,"kind":"persisted"}]}
+```
+
+compact boundary：
+
+```jsonl
+{"type":"system","subtype":"compact_boundary","uuid":"b1","parentUuid":"a9","logicalParentUuid":"a9","sessionId":"s1","compactMetadata":{"trigger":"auto","preTokens":182000,"messagesSummarized":94}}
+```
+
+## 写入生命周期
+
+### 总流程
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant QE as QueryEngine
+  participant SS as sessionStorage.Project
+  participant FS as JSONL
+  participant API as query()/API
+
+  User->>QE: ask(messages)
+  QE->>SS: recordTranscript(user messages)
+  SS->>SS: clean + dedup + insertMessageChain
+  SS->>SS: appendEntry / enqueueWrite
+  SS-->>FS: drain queue append JSONL
+  QE->>API: start query loop
+  API-->>QE: assistant/user/system compact_boundary
+  QE->>SS: recordTranscript(streamed messages)
+  QE->>SS: flushSessionStorage before result when needed
+```
+
+关键点：
+
+| 设计 | 为什么 |
+|---|---|
+| 用户输入先写 transcript，再进 API | 进程在 API 前崩溃时，resume 仍能看到用户 prompt。 |
+| assistant streaming 写入多为 fire-and-forget | 不阻塞 token streaming。 |
+| result 前按需 flush | 避免 SDK/桌面端拿到 result 后立即杀进程导致尾部丢失。 |
+| `progress` 不参与链路 | 高频 progress tick 不应该制造分叉或膨胀 transcript。 |
+
+### 主会话写入
+
+入口：`recordTranscript(messages, teamInfo?, startingParentUuidHint?, allMessages?)`。
+
+流程：
+
+1. `cleanMessagesForLogging()` 过滤 UI-only 或不应持久化的消息。
+2. `getSessionMessages(sessionId)` 读取当前 session 已有 UUID set。
+3. 对未写过的消息调用 `insertMessageChain()`。
+4. `insertMessageChain()` 补 `parentUuid/sessionId/cwd/timestamp/version/gitBranch/isSidechain`。
+5. `appendEntry()` 进入 per-file queue。
+
+去重不是简单丢弃所有重复：如果 prefix 中某些消息已写过，写入器会推进 `startingParentUuid`，确保后续新消息接在正确父节点后。
+
+### 写队列、materialize 和 flush
+
+`Project` 内部维护 per-file queue：
+
+| 机制 | 细节 |
+|---|---|
+| `writeQueues` | `Map<filePath, entry[]>`，按文件聚合写入。 |
+| drain timer | 默认 100ms；CCR/remote persistence 场景约 10ms。 |
+| queue 上限 | 单队列超过 1000 条会丢弃最老 queued entry 并 resolve，防止内存无限增长。 |
+| chunk 上限 | 单次 JSONL append chunk 约 100MB。 |
+| `flushSessionStorage()` | 取消 timer，等待 active drain 和 tracked writes。 |
+
+`sessionFile` 初始为 `null`。这时 title、tag、mode、worktree 等 metadata 先存在内存或 `pendingEntries` 中。第一次出现 `user` 或 `assistant` 时，`materializeSessionFile()` 才创建 session 文件，然后：
+
+1. 写入缓存 metadata。
+2. 回放 pending entries。
+3. 之后所有 entry 正常 append。
+
+这样可以避免“只打开 CLI 没说话”也产生 metadata-only session，污染 `/resume` 列表。
+
+### sidechain 写入
+
+subagent 使用 `recordSidechainTranscript(messages, agentId, startingParentUuid?)`。
+
+它底层仍走 `insertMessageChain()`，但写入字段不同：
+
+```ts
+isSidechain: true
+agentId: agentId
+```
+
+`appendEntry()` 遇到 `isSidechain && agentId` 的 transcript message，会把它路由到：
+
+```text
+<project>/<sessionId>/subagents/agent-<agentId>.jsonl
+```
+
+如果 `content-replacement` 带 `agentId`，也会路由到该 agent 的 sidechain JSONL，而不是主 session JSONL。
+
+一个很重要的例外：sidechain 写入不会用主 session UUID set 做去重。fork agent 会复用父会话消息 UUID 来继承上下文；如果按主 session 去重，会把继承上下文从 sidechain 中误删，导致 agent resume 时只剩子 prompt。
+
+## 读取与链路重建
+
+### 从 JSONL 到有效链
+
+```mermaid
+flowchart TD
+  A[loadTranscriptFile(file)] --> B[readTranscriptForLoad<br/>大文件按 chunk 读]
+  B --> C[parseJSONL Entry]
+  C --> D[messages Map uuid->TranscriptMessage]
+  C --> E[metadata maps/arrays]
+  D --> F[progress bridge / preserved relink / snip removal]
+  F --> G[select leaf]
+  G --> H[buildConversationChain]
+  H --> I[recoverOrphanedParallelToolResults]
+  I --> J[LogOption or agent transcript]
+```
+
+`loadTranscriptFile(filePath, opts?)` 产出：
+
+| 输出 | 用途 |
+|---|---|
+| `messages` | `uuid -> TranscriptMessage`。 |
+| `leafUuids` | 候选 leaf。 |
+| title/tag/mode/worktree/PR maps | session metadata。 |
+| `fileHistorySnapshots` / `attributionSnapshots` | 文件状态恢复。 |
+| `contentReplacements` | 主线程 replacement records。 |
+| `agentContentReplacements` | `agentId -> replacement records`。 |
+| `contextCollapseCommits` / `contextCollapseSnapshot` | context-collapse 恢复输入。 |
+
+### leaf 与 parent 链
+
+`buildConversationChain(messages, leaf)`：
+
+1. 从 leaf 开始。
+2. 读取 `parentUuid`。
+3. 找到父消息并继续回溯。
+4. 检测 parent cycle，避免无限循环。
+5. reverse 成正序 transcript。
+6. 补回并行 tool_use 形成的 DAG 分支。
+
+一个简化例子：
+
+```text
+u1 <- a1 <- u2 <- a2
+                 ^
+               leaf
+
+恢复链: a2 -> u2 -> a1 -> u1
+正序链: u1, a1, u2, a2
+```
+
+文件顺序不等于有效链。branch、rewind、streaming fallback 都可能让 JSONL 里有死分支；恢复只选择当前 leaf 所在世界线。
+
+### metadata 合并规则
+
+| metadata | 合并方式 | 说明 |
+|---|---|---|
+| `custom-title`、`tag`、`mode`、`worktree-state`、`pr-link`、`agent-setting` | sessionId keyed，通常 last-wins | 恢复最新 session 状态。 |
+| `file-history-snapshot`、`attribution-snapshot` | messageId keyed / array | 恢复文件历史与归因。 |
+| `content-replacement` | append array | 多轮 replacement 决策都要保留。 |
+| `agentContentReplacements` | agentId keyed + append array | agent resume 重建 sidechain replacement state。 |
+| `marble-origami-commit` | ordered array | 顺序有语义，后一个 commit 可能引用前一个 summary。 |
+| `marble-origami-snapshot` | last-wins | staged snapshot 只恢复最新状态。 |
+
+### 大文件读取优化
+
+transcript 可增长到几百 MB 甚至 GB，读取路径有几层防护。
+
+| 优化 | 位置 | 目的 |
+|---|---|---|
+| chunk 读取 | `readTranscriptForLoad()` | 避免一次性读爆内存。 |
+| fd 层跳过大 metadata | `readTranscriptForLoad()` | `attribution-snapshot` 等大 entry 不进入 buffer。 |
+| compact 前缀跳过 | `readTranscriptForLoad()` | 遇到非 preserved compact boundary 后，只保留 boundary 后内容。 |
+| pre-boundary metadata scan | `scanPreBoundaryMetadata()` | compact 前被跳过时，仍保留 title/tag/mode/worktree/PR 等展示信息。 |
+| byte-level dead branch 裁剪 | `walkChainBeforeParse()` | JSON.parse 前只拼 active chain 和 metadata，跳过 dead fork/rewind branch。 |
+| lite read 限制 | `MAX_TRANSCRIPT_READ_BYTES` | 直接读 raw transcript 的调用超过约 50MB 要避开。 |
+
+`walkChainBeforeParse()` 只有预计能丢掉至少一半 buffer 时才做 concat，避免优化本身变成额外成本。
+
+### preserved segment 与 snip
+
+compact boundary 可以带 `compactMetadata.preservedSegment`。恢复时 `applyPreservedSegmentRelinks()` 会：
+
+1. 验证 `tailUuid -> headUuid` 链是否完整。
+2. 把 preserved segment 的 head 接到 compact anchor 后。
+3. 把 anchor 的其他 children 接到 preserved tail。
+4. 删除最后一个 boundary 前且不属于 preserved segment 的旧消息。
+5. 清零 preserved assistant 的 usage，避免恢复后马上又触发 autocompact。
+
+示意：
+
+```text
+compact 前: old... -> anchor -> head -> ... -> tail -> next
+compact 后: boundary/summary -> head -> ... -> tail -> next
+```
+
+`snip` 和 compact 不同：compact 截断前缀，snip 删除中段。JSONL 不能真的删除旧行，所以 `applySnipRemovals()` 在内存 map 中删除 `removedUuids`，再把 dangling `parentUuid` 重连到最近未删除祖先。
+
+### 旧链路修复
+
+| 问题 | 修复 |
+|---|---|
+| legacy `progress` 曾进入 parent 链 | `progressBridge` 把指向 progress 的 parent 改回 progress 的真实父节点。 |
+| parent cycle | `buildConversationChain()` 检测 cycle，记录并返回 partial chain。 |
+| 并行 tool_use 形成 DAG | `recoverOrphanedParallelToolResults()` 按 assistant `message.id` 和 tool_result parent 关系补回 sibling。 |
+| streaming fallback 孤儿尾巴 | tombstone 触发 `removeTranscriptMessage(uuid)` 删除失败 attempt。 |
+
+## 恢复入口
+
+### 入口矩阵
+
+| 入口 | 加载源 | 是否复用原 sessionId | 是否 adopt 原 JSONL | 特点 |
+|---|---|---:|---:|---|
+| `--continue` | 当前目录最近 session | 是 | 是 | 跳过仍 live 的 bg/daemon 非 interactive session。 |
+| `--resume <uuid>` | 指定 session | 是 | 是 | 也支持 custom title / 搜索词 / picker。 |
+| `--resume <jsonl>` | 指定 JSONL 文件 | 是 | 是 | Ant 内部/print path 支持。 |
+| `--fork-session` + resume | 旧 session messages | 否 | 否 | 保持新 sessionId，把旧消息作为新 session 初始内容。 |
+| `--resume-session-at <message.id>` | print/headless resume | 取决于 resume | 取决于 resume | 截断到指定 assistant message。 |
+| REPL `/resume` | picker / log option | 是或 fork | 是或否 | 会跑 SessionEnd/SessionStart hooks，切换 UI state。 |
+
+### CLI resume 流程
+
+```mermaid
+flowchart TD
+  A[main.tsx --continue/--resume] --> B[loadConversationForResume]
+  B --> C[load log or transcript]
+  C --> D[deserializeMessagesWithInterruptDetection]
+  D --> E[processSessionStartHooks]
+  E --> F[processResumedConversation]
+  F --> G{fork session?}
+  G -- no --> H[switchSession + adoptResumedSessionFile]
+  G -- yes --> I[keep fresh sessionId + seed content replacement]
+  H --> J[restore mode/worktree/agent/context-collapse/cost]
+  I --> J
+  J --> K[start REPL or print]
+```
+
+核心函数：
+
+| 函数 | 责任 |
+|---|---|
+| `loadConversationForResume()` | 统一加载最近 session、sessionId、LogOption 或 JSONL path；补 lite log；复制 plan/file history；做 consistency check；反序列化和中断检测；返回 metadata。 |
+| `processResumedConversation()` | CLI interactive 启动恢复；切换或 fork session；恢复 cost、worktree、mode、agent setting、context-collapse、attribution。 |
+| `restoreSessionStateFromLog()` | 恢复 AppState 侧状态：file history、attribution、context-collapse、TodoWrite todos。 |
+
+### REPL `/resume`
+
+REPL 内 resume 比 CLI 启动路径多了“从当前 session 切换到另一个 session”的工作：
+
+1. 清理目标 log messages。
+2. 当前 session 跑 SessionEnd hooks。
+3. 目标 session 跑 SessionStart resume hooks。
+4. 保存当前 session cost，恢复目标 session cost。
+5. `switchSession(sessionId, dirname(fullPath))` 原子切换 sessionId + project dir。
+6. `resetSessionFilePointer()` 并恢复 metadata cache。
+7. 非 fork 时退出上一次 worktree，恢复目标 worktree，`adoptResumedSessionFile()`。
+8. fork 时不接管原 transcript，不退出当前 worktree。
+9. 重建 content replacement state。
+10. 恢复 remote/local task 状态。
+11. 替换 messages、清 tool JSX、清输入框。
+
+### 中断检测矩阵
+
+`deserializeMessagesWithInterruptDetection()` 会先清理历史消息：
+
+| 清理 | 目的 |
+|---|---|
+| legacy attachment 迁移 | 兼容旧 transcript。 |
+| 非法 `permissionMode` 删除 | 防止跨 build 的无效枚举进入运行态。 |
+| unresolved tool_use 过滤 | 避免 API 报 tool_use/tool_result 不配对。 |
+| orphaned thinking-only assistant 过滤 | 避免中断 streaming 留下孤儿 thinking block。 |
+| whitespace-only assistant 过滤 | 避免取消时留下空白 assistant。 |
+
+然后看最后一个 turn-relevant message：
+
+| 最后有效消息 | 结果 | 额外动作 |
+|---|---|---|
+| assistant | `none` | streaming 持久化里 stop_reason 常为 null，不能靠它判断未完成。 |
+| 普通 user | `interrupted_prompt` | 插入 `NO_RESPONSE_REQUESTED` sentinel 保持 API-valid。 |
+| meta user / compact summary user | `none` | 不把内部控制消息当用户新请求。 |
+| tool_result user | 通常 `interrupted_turn` | 例外：Brief/SendUserMessage/SendUserFile terminal tool_result 视为完成。 |
+| attachment | `interrupted_turn` | 追加 meta user：`Continue from where you left off.` |
+| system/progress/API error assistant | 跳过 | 不作为 turn 完成判断依据。 |
+
+`interrupted_turn` 会统一转换为 `interrupted_prompt`，让上层只处理一种“需要续跑”的状态。
+
+## 错误恢复矩阵
+
+| 场景 | 处理策略 | transcript 影响 |
+|---|---|---|
+| API 前进程崩溃 | 用户 prompt 已由 `QueryEngine.ask()` 先写入。 | resume 看到普通 user，触发 `interrupted_prompt`。 |
+| streaming fallback 产生孤儿 assistant | yield tombstone，REPL 移除 UI message 并调用 `removeTranscriptMessage(uuid)`。 | 优先只改 JSONL 尾部 64KB；大文件目标不在尾部时跳过慢 rewrite。 |
+| prompt-too-long / media-too-large | streaming 阶段先 withheld；先 context-collapse drain，再 reactive compact；失败才暴露错误。 | compact 成功则写 boundary/summary 并重试；失败才写 API error message。 |
+| max_output_tokens | 先提高 max output override；仍失败则注入内部 recovery prompt 续写；耗尽才暴露错误。 | 内部 retry prompt 不一定成为普通 transcript，取决于是否 yield 到外层。 |
+| auto compact 关闭但到 blocking limit | 直接 yield prompt-too-long 风格 API error。 | 保留用户手动 `/compact` 空间。 |
+| abort during streaming/tools | 补齐缺失 tool_result，必要时 yield user interruption message。 | `reason === interrupt` 时跳过 interruption message，因为后续 queued user message 已提供上下文。 |
+| stop hook blocking | 把 hook blocking error 加入 state 后重试。 | 有 reactive compact guard，避免 hook/error/compact 无限循环。 |
+| compact boundary 指向未落盘 tail | QueryEngine 写 boundary 前强制补写 preserved tail 前的消息。 | 避免恢复时 boundary 引用不存在 UUID。 |
+| subagent transcript 尾部不完整 | `resumeAgentBackground()` 再次过滤 unresolved tool_use、orphan thinking、空白 assistant。 | 避免恢复 agent 后 API 请求非法。 |
+
+## 上下文视图
+
+同一份消息在系统里有四种视图，不要混在一起：
+
+| 视图 | 内容 | 谁使用 |
+|---|---|---|
+| Raw transcript | JSONL 中所有 entry，包括旧历史、dead branch、metadata、sidechain。 | 磁盘持久化和审计。 |
+| UI scrollback | REPL 当前展示的消息，可能保留 compact 前历史和 collapsed UI group。 | 终端 UI。 |
+| Active query view | `getMessagesAfterCompactBoundary()` 后的消息，默认再投影 snip。 | `query.ts` 上下文管理。 |
+| API wire view | `normalizeMessagesForAPI()` 后，过滤 system boundary、修复 tool pairing、插入 cache edits。 | Anthropic/OpenAI/Gemini 等 API client。 |
+
+每轮 query 的 active context 顺序：
+
+1. `getMessagesAfterCompactBoundary(messages)`：取最近 compact boundary 之后的 active slice，默认叠加 snip 投影。
+2. 删除旧 `toolUseResult` 原始 payload，只保留 API 需要的 `message.content`。
+3. `applyToolResultBudget()`：过大的 tool_result 替换为 preview/stub，并写 `content-replacement`。
+4. `snipCompactIfNeeded()`：`HISTORY_SNIP` 下删除中段历史。
+5. `microcompactMessages()`：time-based microcompact，再 cached microcompact。
+6. `contextCollapse.applyCollapsesIfNeeded()`：当前为 identity stub。
+7. `autoCompactIfNeeded()`：主动 compact，优先 session memory compact。
+8. predictive autocompact：API 前估算本 turn 增长，必要时提前 compact。
+9. API 真实超限后：context-collapse drain，再 reactive compact。
+
+## Compact 与投影
+
+### Compact 类型对比
+
+| 类型 | 触发 | 摘要来源 | 是否调用 compact API | 是否保留尾段 | 失败策略 |
+|---|---|---|---:|---:|---|
+| manual compact | `/compact` | compact summary API 或 session memory | 取决于路径 | 取决于 full/partial/SM | 显示失败或回退传统 compact。 |
+| auto compact | token 阈值 | 先 session memory，后 summary API | 取决于路径 | 取决于路径 | 连续失败 circuit breaker，默认 3 次后停止自动 compact。 |
+| predictive compact | API 前估算增长 | 同 auto compact | 取决于路径 | 取决于路径 | 失败则继续原请求或走后续错误恢复。 |
+| reactive compact | API 真实 413/media error 后 | `compactConversation()` | 是 | 当前 wrapper 取决于 compact 实现 | `hasAttemptedReactiveCompact` 防循环。 |
+| session memory compact | manual/auto 前置尝试 | session memory 文件 | 否 | 是 | 若 post-compact 仍超阈值，放弃并回退传统 compact。 |
+| microcompact | time/cached 小型压缩 | 局部清理或 API cache edit | 不一定 | 不适用 | 通常不改变 JSONL 主历史。 |
+| snip | `HISTORY_SNIP` | 删除中段 | 否 | 保留前后上下文 | 通过 snip metadata 投影，不物理删旧行。 |
+
+### Compact 结果形态
+
+传统 compact 会生成：
+
+1. `compact_boundary` system message。
+2. compact summary user message。
+3. post-compact attachments，例如当前文件、计划模式、技能、MCP/tool schema delta、hook 结果。
+
+简化 before/after：
+
+```text
+Raw/UI:
+  u1, a1, u2, a2, ... u99, a99,
+  system:compact_boundary,
+  user:compact summary,
+  attachment:current files,
+  u100
+
+Active query view:
+  system:compact_boundary,
+  user:compact summary,
+  attachment:current files,
+  u100
+
+API wire view:
+  user:compact summary,
+  attachment/content,
+  u100
+```
+
+boundary 本身是 system message，最后会被 API normalization 过滤；它的价值主要在本地投影、恢复和统计。
+
+### Boundary metadata
+
+`createCompactBoundaryMessage()` 写：
+
+| 字段 | 含义 |
+|---|---|
+| `compactMetadata.trigger` | `manual` 或 `auto`。 |
+| `compactMetadata.preTokens` | compact 前 token 数。 |
+| `compactMetadata.userContext` | 用户手动 compact 的额外说明。 |
+| `compactMetadata.messagesSummarized` | 被总结消息数量。 |
+| `logicalParentUuid` | compact 前最后消息，用于逻辑追踪。 |
+
+后续路径还会补：
+
+| 字段 | 来源 | 作用 |
+|---|---|---|
+| `preCompactDiscoveredTools` | traditional/SM compact | 恢复 deferred tool schema 可见性。 |
+| `preservedSegment.{headUuid,anchorUuid,tailUuid}` | partial/SM compact | 恢复时把保留尾段接到 boundary 后。 |
+
+### Tool result budget 与 content replacement
+
+大 tool_result 不一定直接进入后续上下文。`applyToolResultBudget()` 会按 API-level user message 聚合预算，必要时把大块内容持久化并替换成较小 preview/stub。
+
+关键点：
+
+| 点 | 说明 |
+|---|---|
+| replacement decision 会落 JSONL | `recordContentReplacement()` 写 `content-replacement`。 |
+| 主线程和 agent 分开 | 无 `agentId` 写主 JSONL；有 `agentId` 写 sidechain JSONL。 |
+| resume 会重建 replacement state | 避免恢复后同一大结果又变回完整内容，导致 token 暴涨或 prompt cache 失配。 |
+| `--fork-session` 会 seed records | fork 新 session 时复制 replacement 决策到新 session。 |
+
+### Session memory compact
+
+`sessionMemoryCompact.ts` 是传统 summary compact 前的实验路径。流程：
+
+1. 等待 session memory extraction 完成。
+2. 读取 session memory 文件。
+3. 有 `lastSummarizedMessageId` 时，从其后保留安全尾段；否则把 resumed session 视为已有 memory summary。
+4. 调整切点，避免断开 tool_use/tool_result 或 thinking blocks。
+5. 创建标准 `compact_boundary` + summary user message。
+6. 若 post-compact token count 仍超过阈值，放弃并回退传统 compact。
+
+因为产物仍是标准 `CompactionResult`，下游写 transcript 和恢复逻辑与传统 compact 共用。
+
+### Context-collapse 当前状态
+
+本仓库保留了 context-collapse 的持久化接口，但核心实现是 stub：
+
+| 模块 | 当前行为 |
+|---|---|
+| `contextCollapse/index.ts` | `applyCollapsesIfNeeded()` 返回原 messages；`recoverFromOverflow()` 返回 committed=0；`isWithheldPromptTooLong()` 恒 false。 |
+| `contextCollapse/operations.ts` | `projectView()` 是 identity。 |
+| `contextCollapse/persist.ts` | `restoreFromEntries()` 是 no-op。 |
+
+已预留 JSONL entry：
+
+| Entry | 写入接口 | 内容 |
+|---|---|---|
+| `marble-origami-commit` | `recordContextCollapseCommit()` | `collapseId`、summary UUID/content、archived span 边界。 |
+| `marble-origami-snapshot` | `recordContextCollapseSnapshot()` | staged spans、armed、lastSpawnTokens。 |
+
+loader 会收集这些 entry；遇到 compact boundary 时会清空旧 commits/snapshot，避免它们引用已被 compact 丢弃的 UUID。
+
+所以当前真实生效的上下文缩减主要是 compact、session memory compact、tool_result budget、microcompact 和 snip；context-collapse 只是接口已接好。
+
+### Compact 后清理
+
+`runPostCompactCleanup(querySource)` 总是清：
+
+- microcompact state。
+- system prompt sections。
+- classifier approvals。
+- speculative bash checks。
+- beta tracing。
+- session messages memo cache。
+- compact cleanup callbacks。
+- `COMMIT_ATTRIBUTION` 下异步 sweep file-content cache。
+
+只在主线程 compact 清：
+
+- context-collapse store。
+- `getUserContext` cache。
+- memory files cache。
+
+原因：subagent 和主线程同进程，共享模块级状态。`agent:*` compact 如果清主线程 context-collapse 或 memory cache，会破坏父会话状态。
+
+它明确不清 `resetSentSkillNames()`，避免 compact 后重新注入完整 skill listing，浪费 token 和 prompt cache。
+
+## 分支与 Fork 对比
+
+| 入口 | 本质 | 是否新主 session | 是否 subagent | 持久化位置 | 父会话看到什么 | 恢复方式 |
+|---|---|---:|---:|---|---|---|
+| `/branch` | 复制当前主 transcript 成新 JSONL | 是 | 否 | `<newSessionId>.jsonl` | 直接切到新分支会话 | 普通 session resume。 |
+| `--fork-session` | resume/continue 时把旧消息作为新 session 初始消息 | 是 | 否 | 新 session 首次写入时 materialize | 启动即在新 session 中继续 | 新 session resume。 |
+| `/fork <directive>` | slash wrapper，调用 AgentTool fork | 否 | 是 | `subagents/agent-<id>.jsonl` + `.meta.json` | fork started + task notification | `resumeAgentBackground()`。 |
+| `AgentTool({ fork: true })` | Tool 层 fork 子 agent | 否 | 是 | `subagents/agent-<id>.jsonl` + `.meta.json` | sync final tool_result 或 async notification | `resumeAgentBackground()`。 |
+| 普通 AgentTool async | 后台本地 subagent | 否 | 是 | `subagents/agent-<id>.jsonl` + `.meta.json` | `async_launched` + task notification | `resumeAgentBackground()`。 |
+| remote AgentTool | CCR remote session | 否 | 远端 | `remote-agents/*.meta.json` | remote task output/notification | `restoreRemoteAgentTasks()` + CCR。 |
+
+### `/branch`
+
+`/branch` 创建新 session 文件，不是在原 JSONL 里追加 branch marker。
+
+流程：
+
+1. 生成新的 sessionId。
+2. 读取当前 transcript 文件。
+3. 过滤主会话消息，排除 `isSidechain` 和非 transcript entry。
+4. 复制消息并重写 `sessionId`。
+5. 重新串 `parentUuid`。
+6. 添加 `forkedFrom: { sessionId, messageUuid }`。
+7. 复制原 session 的 `content-replacement` entry 并改成新 sessionId。
+8. 写入 `<newSessionId>.jsonl`。
+9. 构造 `LogOption` 并让 REPL resume 到新分支。
+
+### `--fork-session`
+
+`--fork-session` 只改变 resume 的 ownership：
+
+| 非 fork resume | fork-session resume |
+|---|---|
+| 切到旧 sessionId。 | 保持启动时 fresh sessionId。 |
+| `adoptResumedSessionFile()` 接管旧 JSONL。 | 不接管旧 JSONL。 |
+| 后续继续 append 到旧 transcript。 | 后续 materialize 成新 transcript。 |
+| 原 session 继续增长。 | 原 session 不被写入。 |
+
+如果旧 session 有 `content-replacement`，会先把 records seed 到新 session，避免大 tool_result 的替换状态丢失。
+
+## Subagent 与 Fork Agent
+
+### 普通 subagent
+
+普通 AgentTool subagent 最终走 `runAgent()`：
+
+```mermaid
+sequenceDiagram
+  participant Parent as 父会话
+  participant Tool as AgentTool
+  participant Agent as runAgent
+  participant Side as sidechain JSONL
+  participant Task as LocalAgentTask
+
+  Parent->>Tool: assistant tool_use Agent
+  Tool->>Agent: start sync or async
+  Agent->>Side: record initialMessages
+  Agent->>Side: record assistant/user/progress/compact_boundary
+  alt sync foreground
+    Agent-->>Tool: final result
+    Tool-->>Parent: Agent tool_result
+  else async/background
+    Tool-->>Parent: async_launched tool_result
+    Agent-->>Task: complete
+    Task-->>Parent: <task-notification>
+  end
+```
+
+父会话通常只记录：
+
+- Agent tool_use。
+- Agent tool_result。
+- async launch result。
+- task notification。
+- 必要 progress。
+
+完整子 agent 内部工具调用和消息在 sidechain JSONL 中，不会混进主会话 active context。
+
+### Fork agent
+
+fork agent 是 AgentTool 的一种特殊 subagent。它继承父上下文、system prompt、tools、model 和 thinking config，目标是让多个子 agent 共享尽可能长的 byte-identical prompt cache prefix。
+
+关键实现：
+
+| 继承内容 | 实现 |
+|---|---|
+| system prompt | 优先使用 `toolUseContext.renderedSystemPrompt`，没有才 fallback 重建。 |
+| tools | 使用父 `toolUseContext.options.tools`，`useExactTools: true`。 |
+| model | `FORK_AGENT.model = "inherit"`。 |
+| thinking/non-interactive | 通过 exact tool/options 继承，避免 cache key 分叉。 |
+| messages | `forkContextMessages = toolUseContext.messages`。 |
+
+`buildForkedMessages()` 负责构造 cache-friendly 尾部：
+
+```text
+parent history...
+assistant: [text/thinking/tool_use A/tool_use B/...]
+user:
+  tool_result for A = "Fork started — processing in background"
+  tool_result for B = "Fork started — processing in background"
+  directive = "<this fork's task>"
+```
+
+多个 fork child 的长前缀相同，只有最后 directive 不同。
+
+限制：
+
+| 限制 | 原因 |
+|---|---|
+| 需要 `FORK_SUBAGENT` feature。 | 功能门控。 |
+| coordinator mode 禁用。 | coordinator 已有自己的编排模型。 |
+| non-interactive session 禁用。 | fork subagent 偏交互式后台任务模型。 |
+| fork child 禁止递归 fork。 | 防止无限 fork；通过 querySource 和 boilerplate tag 检测。 |
+| resume fork agent 不再传 `forkContextMessages`。 | sidechain 已包含父上下文切片，重复传会造成重复 tool_use id。 |
+
+### `runForkedAgent()` 不是 AgentTool fork
+
+`src/utils/forkedAgent.ts` 的 `runForkedAgent()` 是内部 cache-safe side query 工具，用于 session memory、prompt suggestion、summary 等。它复用父 system/user/system context、tools、messages，可选 `skipTranscript`，但默认不写 AgentTool metadata，也不是用户可继续对话的 AgentTool fork。
+
+## Agent 恢复
+
+本地 agent 恢复入口是 `resumeAgentBackground()`。
+
+流程：
+
+```mermaid
+flowchart TD
+  A[user continues agent] --> B[getAgentTranscript(agentId)]
+  B --> C[load sidechain JSONL + build chain]
+  C --> D[readAgentMetadata(agentId)]
+  D --> E[filter unresolved tool_use/thinking/blank assistant]
+  E --> F[reconstruct content replacement state]
+  F --> G{metadata.worktreePath exists?}
+  G -- yes --> H[runWithCwdOverride(worktreePath)]
+  G -- no --> I[parent cwd]
+  H --> J[register async LocalAgentTask]
+  I --> J
+  J --> K[continue query loop]
+```
+
+恢复时：
+
+| 状态 | 来源 |
+|---|---|
+| agent transcript | `agent-<agentId>.jsonl`。 |
+| agent type | `agent-<agentId>.meta.json`。 |
+| fork/general agent 选择 | metadata `agentType`。 |
+| worktree cwd | metadata `worktreePath`，目录不存在则回退父 cwd。 |
+| content replacement | sidechain records + parent live state gap-fill。 |
+| task UI | 重新注册 async task。 |
+
+## Remote Agent 恢复
+
+remote CCR agent 不靠本地 sidechain 继续执行。
+
+```mermaid
+sequenceDiagram
+  participant Tool as AgentTool
+  participant R as RemoteAgentTask
+  participant Sidecar as remote-agents meta
+  participant CCR as CCR session
+  participant REPL as REPL resume
+
+  Tool->>CCR: teleportToRemote()
+  Tool->>R: registerRemoteAgentTask()
+  R->>Sidecar: write remote-agent-<taskId>.meta.json
+  REPL->>Sidecar: restoreRemoteAgentTasks()
+  REPL->>CCR: fetchSession(sessionId)
+  alt running
+    REPL->>R: rebuild RemoteAgentTaskState + polling
+  else 404/archive
+    REPL->>Sidecar: delete sidecar
+  end
+```
+
+差异：
+
+| 本地 subagent | remote agent |
+|---|---|
+| 有完整 sidechain JSONL。 | 没有本地执行 transcript。 |
+| resume 可继续 API 对话。 | resume 只恢复 polling。 |
+| 状态来自 JSONL + `.meta.json`。 | 状态来自 CCR session + local sidecar。 |
+| 完成后本地 sidechain 仍可审计。 | 完成/archived 后 sidecar 会删除。 |
+
+## 常见误区
+
+| 误区 | 正确理解 |
+|---|---|
+| JSONL 顺序就是会话顺序 | 恢复靠 leaf + `parentUuid`，不是简单顺序 replay。 |
+| compact 删除了旧历史 | compact 追加 boundary；旧历史仍在 raw transcript。 |
+| boundary 会发给模型 | boundary 是本地 system marker，API normalization 会过滤。 |
+| `/branch` 和 `/fork` 都是 fork | `/branch` 是新主 session；`/fork` 是 fork subagent sidechain。 |
+| `--fork-session` 等于 `/branch` | 它不是复制文件命令，而是 resume 时保持 fresh session ownership。 |
+| subagent 消息会进入主上下文 | 父会话只看到 Agent tool result/notification，完整内部消息在 sidechain。 |
+| remote agent 有本地 sidechain | remote 只有 sidecar 身份，执行状态来自 CCR。 |
+| context-collapse 已经真实压缩上下文 | 当前仓库中 context-collapse 核心实现是 stub。 |
+
+## 源码入口索引
+
+| 问题 | 从这里看 |
+|---|---|
+| Entry union 有哪些类型 | `src/types/logs.ts` 的 `Entry`。 |
+| 主 transcript 路径 | `src/utils/sessionStorage.ts` 的 `getTranscriptPath()`。 |
+| subagent transcript 路径 | `getAgentTranscriptPath(agentId)`。 |
+| remote sidecar 路径 | `getRemoteAgentsDir()` / `getRemoteAgentMetadataPath()`。 |
+| 主写入 | `recordTranscript()`。 |
+| sidechain 写入 | `recordSidechainTranscript()`。 |
+| write queue | `Project.enqueueWrite()` / `drainWriteQueue()` / `flush()`。 |
+| lazy materialize | `Project.materializeSessionFile()`。 |
+| tombstone 删除 | `removeTranscriptMessage()` / `Project.removeMessageByUuid()`。 |
+| 读取 transcript | `loadTranscriptFile()`。 |
+| 大文件读取 | `readTranscriptForLoad()` in `sessionStoragePortable.ts`。 |
+| dead branch 裁剪 | `walkChainBeforeParse()`。 |
+| parent 链重建 | `buildConversationChain()`。 |
+| parallel tool_result 补回 | `recoverOrphanedParallelToolResults()`。 |
+| preserved segment | `applyPreservedSegmentRelinks()`。 |
+| snip removal | `applySnipRemovals()`。 |
+| CLI resume 加载 | `loadConversationForResume()`。 |
+| resume 状态切换 | `processResumedConversation()`。 |
+| AppState 恢复 | `restoreSessionStateFromLog()`。 |
+| 中断检测 | `deserializeMessagesWithInterruptDetection()`。 |
+| active context | `getMessagesAfterCompactBoundary()`。 |
+| query context pipeline | `src/query.ts`。 |
+| compact boundary | `createCompactBoundaryMessage()`。 |
+| auto compact | `autoCompactIfNeeded()` / `shouldAutoCompact()`。 |
+| session memory compact | `src/services/compact/sessionMemoryCompact.ts`。 |
+| reactive compact | `src/services/compact/reactiveCompact.ts`。 |
+| post compact cleanup | `runPostCompactCleanup()`。 |
+| context-collapse stub | `src/services/contextCollapse/*`。 |
+| `/branch` | `src/commands/branch/branch.ts`。 |
+| `/fork` | `src/commands/fork/fork.tsx`。 |
+| AgentTool fork | `AgentTool.tsx` + `forkSubagent.ts`。 |
+| 普通 subagent 运行 | `runAgent.ts`。 |
+| agent resume | `resumeAgent.ts`。 |
+| remote task restore | `restoreRemoteAgentTasks()`。 |

docs/performance-reporter.md

@@ -0,0 +1,54 @@
+# 内存占用 1G 调研报告
+
+> 诊断 session `a3593062` RSS 达 1.09 GB，定位 Bun 运行时内存膨胀根因
+
+## 数据收集
+
+- **诊断数据**: RSS 1,118 MB，V8 heap 84 MB，原生内存缺口 1,034 MB（92%）
+- **构建方式**: `bun run build:vite` → Vite/Rollup 单文件构建，产物 17MB `dist/cli.js`
+- **Vite 配置**: `codeSplitting: false`（`vite.config.ts:97`），所有代码内联为单文件
+- **Node.js 对比**: 相同 17MB 产物，Node.js RSS 仅 223 MB（`--version`）/ 340 MB（完整加载）
+
+## 探索与验证
+
+### 已确认
+
+| 问题 | 位置 | 说明 |
+|------|------|------|
+| **根因: Vite 单文件构建 + Bun 解析大文件内存效率低** | `vite.config.ts:97` | `codeSplitting: false` 产出 17MB 单文件，Bun/JSC 解析时 RSS 暴涨至 966MB |
+| Node.js 对同等 17MB 文件仅需 223MB | 实测 | V8 对大文件解析的内存效率远优于 JSC |
+| Bun.build 代码分割可解决问题 | 实测 | `bun run build`（代码分割 → 627 chunk）Bun RSS 仅 30MB（`--version`）/ 318MB（完整加载） |
+
+### 已否认
+
+- 不是 feature flags 数量问题 — 全部 35 features 开启时，代码分割构建内存正常
+- 不是内存泄漏 — `detachedContexts: 0`，`activeHandles: 0`
+- 不是原生 addon 问题 — vendor 文件仅 2.7MB
+- 不是 TypeScript 源码体量问题 — `bun run dev`（直接加载 TS）完整路径仅 345MB
+
+## 结论
+
+**根因是 Vite 构建配置 `codeSplitting: false`，产出 17MB 单文件，Bun/JSC 解析单文件大 JS 时内存效率极差（966MB vs Node 的 223MB）。**
+
+实测对比矩阵：
+
+| 构建方式 | 产物结构 | Bun RSS | Node RSS | Bun/Node |
+|----------|----------|---------|----------|----------|
+| `build:vite` | 17MB 单文件 | **966 MB** | 223 MB | 4.3x |
+| `build:vite` pipe mode | 同上 | **1,088 MB** | 340 MB | 3.2x |
+| `build` (Bun) | 627 chunk | 30 MB | 42 MB | 0.7x |
+| `build` (Bun) pipe mode | 同上 | 318 MB | 253 MB | 1.3x |
+| `bun run dev` TS 源码 | 动态加载 | 42 MB | — | — |
+| `bun run dev` pipe mode | 动态加载 | 345 MB | — | — |
+
+核心差异：
+- **Node/V8** 解析 17MB 文件只需 223MB — V8 的懒解析（lazy parsing）只编译入口需要的部分
+- **Bun/JSC** 解析 17MB 文件需要 966MB — JSC 对单文件做全量编译，bytecode + JIT 占用大量原生内存
+- 代码分割后（627 个小 chunk），Bun 按需加载，内存回到正常水平
+
+## 建议
+
+1. **开启 Vite 代码分割** — 在 `vite.config.ts` 中启用 `codeSplitting: true` 或使用 Rollup 的 `manualChunks` 配置。这是最直接的修复
+2. **或切换到 Bun.build** — `bun run build` 已默认启用代码分割（`splitting: true`），Bun RSS 仅 30-318MB
+3. **如果必须单文件** — 考虑用 Node.js 运行 Vite 产物（`node dist/cli-node.js`），代价是失去 Bun 特有 API
+4. **验证 `codeSplitting: false` 的存在理由** — 注释说"all dynamic imports inlined"，可能是为了简化部署。评估是否真的需要单文件

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-best",
-  "version": "2.4.3",
+  "version": "2.6.13",
   "description": "Reverse-engineered Anthropic Claude Code CLI — interactive AI coding assistant in the terminal",
   "type": "module",
   "author": "claude-code-best <claude-code-best@proton.me>",

packages/@ant/claude-for-chrome-mcp/src/bridgeClient.ts

@@ -9,6 +9,7 @@ import { SocketConnectionError } from './mcpSocketClient.js'
 import {
   localPlatformLabel,
   type BridgePermissionRequest,
+  toLoggerDetail,
   type ChromeExtensionInfo,
   type ClaudeForChromeContext,
   type PermissionMode,
@@ -578,7 +579,7 @@ export class BridgeClient implements SocketClient {
       const durationMs = Date.now() - this.connectionStartTime
       logger.error(
         `[${serverName}] Failed to create WebSocket after ${durationMs}ms:`,
-        error,
+        toLoggerDetail(error),
       )
       trackEvent?.('chrome_bridge_connection_failed', {
         duration_ms: durationMs,
@@ -618,7 +619,10 @@ export class BridgeClient implements SocketClient {
         )
         this.handleMessage(message)
       } catch (error) {
-        logger.error(`[${serverName}] Failed to parse bridge message:`, error)
+        logger.error(
+          `[${serverName}] Failed to parse bridge message:`,
+          toLoggerDetail(error),
+        )
       }
     })
 
@@ -862,7 +866,10 @@ export class BridgeClient implements SocketClient {
       const allowed = await pending.onPermissionRequest(request)
       this.sendPermissionResponse(requestId, allowed)
     } catch (error) {
-      logger.error(`[${serverName}] Error handling permission request:`, error)
+      logger.error(
+        `[${serverName}] Error handling permission request:`,
+        toLoggerDetail(error),
+      )
       this.sendPermissionResponse(requestId, false)
     }
   }

packages/@ant/claude-for-chrome-mcp/src/index.ts

@@ -8,8 +8,11 @@ export { localPlatformLabel } from './types.js'
 export type {
   BridgeConfig,
   ChromeExtensionInfo,
+  ChromeBridgeTrackEventMetadata,
   ClaudeForChromeContext,
   Logger,
+  LoggerDetail,
   PermissionMode,
   SocketClient,
 } from './types.js'
+export { toLoggerDetail } from './types.js'

packages/@ant/claude-for-chrome-mcp/src/mcpSocketClient.ts

@@ -9,6 +9,7 @@ import type {
   PermissionMode,
   PermissionOverrides,
 } from './types.js'
+import { toLoggerDetail } from './types.js'
 
 export class SocketConnectionError extends Error {
   constructor(message: string) {
@@ -87,7 +88,10 @@ class McpSocketClient {
       await this.validateSocketSecurity(socketPath)
     } catch (error) {
       this.connecting = false
-      logger.info(`[${serverName}] Security validation failed:`, error)
+      logger.info(
+        `[${serverName}] Security validation failed:`,
+        toLoggerDetail(error),
+      )
       // Don't retry on security failures (wrong perms/owner) - those won't
       // self-resolve. Only the error handler retries on transient errors.
       return
@@ -145,14 +149,20 @@ class McpSocketClient {
             logger.info(`[${serverName}] Received unknown message: ${message}`)
           }
         } catch (error) {
-          logger.info(`[${serverName}] Failed to parse message:`, error)
+          logger.info(
+            `[${serverName}] Failed to parse message:`,
+            toLoggerDetail(error),
+          )
         }
       }
     })
 
     this.socket.on('error', (error: Error & { code?: string }) => {
       clearTimeout(connectTimeout)
-      logger.info(`[${serverName}] Socket error (code: ${error.code}):`, error)
+      logger.info(
+        `[${serverName}] Socket error (code: ${error.code}):`,
+        toLoggerDetail(error),
+      )
       this.connected = false
       this.connecting = false
 

packages/@ant/claude-for-chrome-mcp/src/toolCalls.ts

@@ -7,6 +7,7 @@ import type {
   PermissionOverrides,
   SocketClient,
 } from './types.js'
+import { toLoggerDetail } from './types.js'
 
 export const handleToolCall = async (
   context: ClaudeForChromeContext,
@@ -44,7 +45,10 @@ export const handleToolCall = async (
 
     return handleToolCallDisconnected(context)
   } catch (error) {
-    context.logger.info(`[${context.serverName}] Error calling tool:`, error)
+    context.logger.info(
+      `[${context.serverName}] Error calling tool:`,
+      toLoggerDetail(error),
+    )
 
     if (error instanceof SocketConnectionError) {
       return handleToolCallDisconnected(context)
@@ -165,8 +169,7 @@ async function handleToolCallConnected(
 
   // Fallback for unexpected result format
   context.logger.warn(
-    `[${context.serverName}] Unexpected result format from socket bridge`,
-    response,
+    `[${context.serverName}] Unexpected result format from socket bridge: ${JSON.stringify(response)}`,
   )
 
   return {

packages/@ant/claude-for-chrome-mcp/src/types.ts

@@ -1,11 +1,84 @@
-export interface Logger {
-  info: (message: string, ...args: unknown[]) => void
-  error: (message: string, ...args: unknown[]) => void
-  warn: (message: string, ...args: unknown[]) => void
-  debug: (message: string, ...args: unknown[]) => void
-  silly: (message: string, ...args: unknown[]) => void
+/**
+ * Logger 第二参数的可选类型。
+ * 调用方通过 util.format 追加详情，实践中多为 catch 到的异常对象。
+ */
+export type LoggerDetail = Error | NodeJS.ErrnoException
+
+/** 将 unknown 收窄为 LoggerDetail，供 catch 块传给 logger 使用。 */
+export function toLoggerDetail(detail: unknown): LoggerDetail | undefined {
+  return detail instanceof Error ? detail : undefined
 }
 
+/** 宿主注入的日志接口，与 DebugLogger（util.format）对齐。 */
+export interface Logger {
+  info: (message: string, detail?: LoggerDetail) => void // 信息
+  error: (message: string, detail?: LoggerDetail) => void // 错误
+  warn: (message: string, detail?: LoggerDetail) => void // 警告
+  debug: (message: string, detail?: LoggerDetail) => void // 调试
+  silly: (message: string, detail?: LoggerDetail) => void // 最细粒度调试
+}
+
+/**
+ * Bridge 连接失败时的 error_type 枚举。
+ * 由 bridgeClient 在 getUserId / getOAuthToken / WebSocket 创建失败时上报。
+ */
+export type ChromeBridgeConnectionErrorType =
+  | 'no_user_id' // 无法获取用户 UUID
+  | 'no_oauth_token' // 无法获取 OAuth token
+  | 'websocket_error' // WebSocket 创建或运行异常
+
+/** 工具调用相关遥测元数据（started / completed / timeout / error）。 */
+export type ChromeBridgeToolCallMetadata = {
+  tool_name: string // MCP 工具名
+  tool_use_id: string // 本次调用的 UUID
+  duration_ms?: number // 耗时（毫秒）
+  timeout_ms?: number // 超时阈值（毫秒），仅 timeout 事件
+  error_message?: string // 错误摘要（截断），仅 error 事件
+}
+
+/** Bridge 连接失败遥测元数据。 */
+export type ChromeBridgeConnectionFailedMetadata = {
+  duration_ms: number // 自连接开始到失败的耗时（毫秒）
+  error_type: ChromeBridgeConnectionErrorType // 失败原因分类
+  reconnect_attempt: number // 当前重连尝试次数
+}
+
+/** Bridge 开始连接遥测元数据。 */
+export type ChromeBridgeConnectionStartedMetadata = {
+  bridge_url: string // 目标 WebSocket URL（含用户路径）
+}
+
+/** Bridge 断开连接遥测元数据。 */
+export type ChromeBridgeDisconnectedMetadata = {
+  close_code: number // WebSocket 关闭码
+  duration_since_connect_ms: number // 自连接成功到断开的时长（毫秒）
+  reconnect_attempt: number // 即将进行的重连序号
+}
+
+/** Bridge 连接成功遥测元数据。 */
+export type ChromeBridgeConnectionSucceededMetadata = {
+  duration_ms: number // 自开始到连接就绪的耗时（毫秒）
+  status: 'paired' | 'waiting' // paired=已配对扩展；waiting=等待扩展接入
+}
+
+/** Bridge 重连次数耗尽遥测元数据。 */
+export type ChromeBridgeReconnectExhaustedMetadata = {
+  total_attempts: number // 累计重连次数上限
+}
+
+/**
+ * trackEvent 回调的 metadata 联合类型。
+ * 各变体对应 bridgeClient 内 chrome_bridge_* 事件；null 表示无附加字段。
+ */
+export type ChromeBridgeTrackEventMetadata =
+  | ChromeBridgeToolCallMetadata
+  | ChromeBridgeConnectionFailedMetadata
+  | ChromeBridgeConnectionStartedMetadata
+  | ChromeBridgeDisconnectedMetadata
+  | ChromeBridgeConnectionSucceededMetadata
+  | ChromeBridgeReconnectExhaustedMetadata
+  | null // 无元数据（如 peer_connected / peer_disconnected）
+
 export type PermissionMode =
   | 'ask'
   | 'skip_all_permission_checks'
@@ -48,10 +121,10 @@ export interface ClaudeForChromeContext {
   bridgeConfig?: BridgeConfig
   /** If set, permission mode is sent to the extension immediately on bridge connection. */
   initialPermissionMode?: PermissionMode
-  /** Optional callback to track telemetry events for bridge connections */
-  trackEvent?: <K extends string>(
-    eventName: K,
-    metadata: Record<string, unknown> | null,
+  /** Bridge 遥测回调；eventName 为 chrome_bridge_* 事件名 */
+  trackEvent?: (
+    eventName: string, // 事件名
+    metadata: ChromeBridgeTrackEventMetadata, // 事件元数据
   ) => void
   /** Called when user pairs with an extension via the browser pairing flow. */
   onExtensionPaired?: (deviceId: string, name: string) => void

packages/@ant/computer-use-mcp/src/pixelCompare.ts

@@ -20,7 +20,7 @@
  */
 
 import type { ScreenshotResult } from './executor.js'
-import type { Logger } from './types.js'
+import { type Logger, toLoggerDetail } from './types.js'
 
 /** Injected by the host. See `ComputerUseHostAdapter.cropRawPatch`. */
 export type CropRawPatchFn = (
@@ -165,7 +165,10 @@ export async function validateClickTarget(
   } catch (err) {
     // Skip validation on technical errors, execute action anyway.
     // Battle-tested: validation failure must never block the click.
-    logger.debug('[pixelCompare] validation error, skipping', err)
+    logger.debug(
+      '[pixelCompare] validation error, skipping',
+      toLoggerDetail(err),
+    )
     return { valid: true, skipped: true }
   }
 }

packages/@ant/computer-use-mcp/src/toolCalls.ts

@@ -91,6 +91,7 @@ import type {
   ResolvedAppRequest,
   TeachStepRequest,
 } from './types.js'
+import { toLoggerDetail } from './types.js'
 
 /**
  * Finder is never hidden by the hide loop (hiding Finder kills the Desktop),
@@ -4446,7 +4447,10 @@ export async function handleToolCall(
     // For ungated tools, the executor may have been mid-call; that's fine —
     // the result is still a tool error, never an implicit success.
     const msg = err instanceof Error ? err.message : String(err)
-    logger.error(`[${serverName}] tool=${name} threw: ${msg}`, err)
+    logger.error(
+      `[${serverName}] tool=${name} threw: ${msg}`,
+      toLoggerDetail(err),
+    )
     return errorResult(`Tool "${name}" failed: ${msg}`, 'executor_threw')
   }
 }

packages/@ant/computer-use-mcp/src/types.ts

@@ -8,13 +8,24 @@ import type {
  *  cross-respawn `scaleCoord` survival. */
 export type ScreenshotDims = Omit<ScreenshotResult, 'base64'>
 
-/** Shape mirrors claude-for-chrome-mcp/src/types.ts:1-7 */
+/**
+ * Logger 第二参数的可选类型（与 claude-for-chrome-mcp 对齐）。
+ * 实践中多为 catch 到的 Error。
+ */
+export type LoggerDetail = Error | NodeJS.ErrnoException
+
+/** 将 unknown 收窄为 LoggerDetail，供 catch 块传给 logger 使用。 */
+export function toLoggerDetail(detail: unknown): LoggerDetail | undefined {
+  return detail instanceof Error ? detail : undefined
+}
+
+/** 宿主注入的日志接口（与 claude-for-chrome-mcp/src/types.ts 对齐）。 */
 export interface Logger {
-  info: (message: string, ...args: unknown[]) => void
-  error: (message: string, ...args: unknown[]) => void
-  warn: (message: string, ...args: unknown[]) => void
-  debug: (message: string, ...args: unknown[]) => void
-  silly: (message: string, ...args: unknown[]) => void
+  info: (message: string, detail?: LoggerDetail) => void // 信息
+  error: (message: string, detail?: LoggerDetail) => void // 错误
+  warn: (message: string, detail?: LoggerDetail) => void // 警告
+  debug: (message: string, detail?: LoggerDetail) => void // 调试
+  silly: (message: string, detail?: LoggerDetail) => void // 最细粒度调试
 }
 
 /**

packages/@ant/ink/src/core/cursor.ts

@@ -1,2 +1,6 @@
-// Auto-generated stub — replace with real implementation
-export type Cursor = any
+/** 渲染帧中虚拟终端光标的状态（列/行坐标与是否绘制），供 diff 与光标 preamble 使用。 */
+export type Cursor = {
+  x: number // 光标所在列，从 0 开始计
+  y: number // 光标所在行，从 0 开始计
+  visible: boolean // 本帧是否应在终端绘制光标（隐藏时不发射光标移动序列）
+}

packages/@ant/ink/src/core/dom.ts

@@ -1,3 +1,4 @@
+import type { EventHandlerProps } from './events/event-handlers.js'
 import type { FocusManager } from './focus.js'
 import { createLayoutNode } from './layout/engine.js'
 import type { LayoutNode } from './layout/node.js'
@@ -45,10 +46,9 @@ export type DOMElement = {
   dirty: boolean
   // Set by the reconciler's hideInstance/unhideInstance; survives style updates.
   isHidden?: boolean
-  // Event handlers set by the reconciler for the capture/bubble dispatcher.
-  // Stored separately from attributes so handler identity changes don't
-  // mark dirty and defeat the blit optimization.
-  _eventHandlers?: Record<string, unknown>
+  // 协调器写入的事件处理器（捕获/冒泡分发用）。
+  // 与 attributes 分离，避免 handler 引用变化触发 dirty 破坏 blit 优化。
+  _eventHandlers?: Partial<EventHandlerProps> // 见 event-handlers.ts EventHandlerProps
 
   // Scroll state for overflow: 'scroll' boxes. scrollTop is the number of
   // rows the content is scrolled down by. scrollHeight/scrollViewportHeight

packages/@ant/ink/src/core/events/paste-event.ts

@@ -1,2 +1,4 @@
-// Auto-generated stub — replace with real implementation
-export type PasteEvent = any
+/** Box 等组件上 `onPaste` / `onPasteCapture` 收到的粘贴事件形状（与括号粘贴解析结果对齐的占位约定）。 */
+export type PasteEvent = {
+  pastedText: string // 终端括号粘贴模式下解析出的 UTF-8 文本；允许为空字符串以表示空粘贴
+}

packages/@ant/ink/src/core/events/resize-event.ts

@@ -1,2 +1,5 @@
-// Auto-generated stub — replace with real implementation
-export type ResizeEvent = any
+/** 终端尺寸变化时 `onResize` 回调收到的事件载荷（与 `stdout.columns` / `stdout.rows` 一致）。 */
+export type ResizeEvent = {
+  columns: number // 当前终端列数（宽度）
+  rows: number // 当前终端行数（高度）
+}

packages/@ant/ink/src/core/events/terminal-event.ts

@@ -101,7 +101,10 @@ export class TerminalEvent extends Event {
   _prepareForTarget(_target: EventTarget): void {}
 }
 
+import type { EventHandlerProps } from './event-handlers.js'
+
+/** 终端事件系统的目标节点（DOM 树节点或根节点）。 */
 export type EventTarget = {
-  parentNode: EventTarget | undefined
-  _eventHandlers?: Record<string, unknown>
+  parentNode: EventTarget | undefined // 父节点，根节点为 undefined
+  _eventHandlers?: Partial<EventHandlerProps> // 事件处理器，与 dom.ts DOMElement 同构
 }

packages/@ant/ink/src/core/reconciler.ts

@@ -20,7 +20,10 @@ import {
   type TextNode,
 } from './dom.js'
 import { Dispatcher } from './events/dispatcher.js'
-import { EVENT_HANDLER_PROPS } from './events/event-handlers.js'
+import {
+  EVENT_HANDLER_PROPS,
+  type EventHandlerProps,
+} from './events/event-handlers.js'
 import { getFocusManager, getRootNode } from './focus.js'
 import { LayoutDisplay } from './layout/node.js'
 import applyStyles, { type Styles, type TextStyles } from './styles.js'
@@ -111,7 +114,11 @@ type HostContext = {
   isInsideText: boolean
 }
 
-function setEventHandler(node: DOMElement, key: string, value: unknown): void {
+function setEventHandler<K extends keyof EventHandlerProps>(
+  node: DOMElement,
+  key: K,
+  value: EventHandlerProps[K],
+): void {
   if (!node._eventHandlers) {
     node._eventHandlers = {}
   }
@@ -135,7 +142,11 @@ function applyProp(node: DOMElement, key: string, value: unknown): void {
   }
 
   if (EVENT_HANDLER_PROPS.has(key)) {
-    setEventHandler(node, key, value)
+    setEventHandler(
+      node,
+      key as keyof EventHandlerProps,
+      value as EventHandlerProps[keyof EventHandlerProps],
+    )
     return
   }
 
@@ -441,7 +452,11 @@ const reconciler = createReconciler<
         }
 
         if (EVENT_HANDLER_PROPS.has(key)) {
-          setEventHandler(node, key, value)
+          setEventHandler(
+            node,
+            key as keyof EventHandlerProps,
+            value as EventHandlerProps[keyof EventHandlerProps],
+          )
           continue
         }
 

packages/@ant/model-provider/src/providers/gemini/streamAdapter.ts

@@ -16,6 +16,7 @@ export async function* adaptGeminiStreamToAnthropic(
   let finishReason: string | undefined
   let inputTokens = 0
   let outputTokens = 0
+  let cachedReadTokens = 0
 
   for await (const chunk of stream) {
     const usage = chunk.usageMetadata
@@ -23,6 +24,7 @@ export async function* adaptGeminiStreamToAnthropic(
       inputTokens = usage.promptTokenCount ?? inputTokens
       outputTokens =
         (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0)
+      cachedReadTokens = usage.cachedContentTokenCount ?? cachedReadTokens
     }
 
     if (!started) {
@@ -41,7 +43,7 @@ export async function* adaptGeminiStreamToAnthropic(
             input_tokens: inputTokens,
             output_tokens: 0,
             cache_creation_input_tokens: 0,
-            cache_read_input_tokens: 0,
+            cache_read_input_tokens: cachedReadTokens,
           },
         },
       } as unknown as BetaRawMessageStreamEvent
@@ -204,7 +206,10 @@ export async function* adaptGeminiStreamToAnthropic(
         stop_sequence: null,
       },
       usage: {
+        input_tokens: inputTokens,
         output_tokens: outputTokens,
+        cache_creation_input_tokens: 0,
+        cache_read_input_tokens: cachedReadTokens,
       },
     } as BetaRawMessageStreamEvent
 

packages/@ant/model-provider/src/providers/gemini/types.ts

@@ -68,6 +68,7 @@ export type GeminiUsageMetadata = {
   candidatesTokenCount?: number
   thoughtsTokenCount?: number
   totalTokenCount?: number
+  cachedContentTokenCount?: number
 }
 
 export type GeminiCandidate = {

packages/@ant/model-provider/src/shared/__tests__/openaiStreamAdapter.test.ts

@@ -551,7 +551,8 @@ describe('prompt caching support', () => {
 
     const msgStart = events.find(e => e.type === 'message_start') as any
     expect(msgStart.message.usage.cache_read_input_tokens).toBe(800)
-    expect(msgStart.message.usage.input_tokens).toBe(1000)
+    // input_tokens = prompt_tokens - cached_tokens = 1000 - 800 = 200
+    expect(msgStart.message.usage.input_tokens).toBe(200)
   })
 
   test('defaults cache_read_input_tokens to 0 when no cached_tokens', async () => {
@@ -750,7 +751,8 @@ describe('prompt caching support', () => {
 
     // message_delta carries the real values from the trailing chunk
     const msgDelta = events.find(e => e.type === 'message_delta') as any
-    expect(msgDelta.usage.input_tokens).toBe(30011)
+    // input_tokens = prompt_tokens - cached_tokens = 30011 - 19904 = 10107
+    expect(msgDelta.usage.input_tokens).toBe(10107)
     expect(msgDelta.usage.output_tokens).toBe(190)
     expect(msgDelta.usage.cache_read_input_tokens).toBe(19904)
     expect(msgDelta.usage.cache_creation_input_tokens).toBe(0)
@@ -821,7 +823,34 @@ describe('prompt caching support', () => {
 
     const msgDelta = events.find(e => e.type === 'message_delta') as any
     expect(msgDelta.usage.cache_read_input_tokens).toBe(1500)
-    expect(msgDelta.usage.input_tokens).toBe(2000)
+    // input_tokens = prompt_tokens - cached_tokens = 2000 - 1500 = 500
+    expect(msgDelta.usage.input_tokens).toBe(500)
     expect(msgDelta.usage.output_tokens).toBe(100)
   })
+
+  test('subtracts cached_tokens from input_tokens to match Anthropic semantic', async () => {
+    // Anthropic's input_tokens = non-cached tokens only.
+    // OpenAI's prompt_tokens = total input including cached.
+    // The adapter must subtract: input_tokens = prompt_tokens - cached_tokens.
+    const events = await collectEvents([
+      makeChunk({
+        choices: [{ index: 0, delta: { content: 'hi' }, finish_reason: null }],
+      }),
+      makeChunk({
+        choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+        usage: {
+          prompt_tokens: 34097,
+          completion_tokens: 30,
+          total_tokens: 34127,
+          prompt_tokens_details: { cached_tokens: 34048 },
+        } as any,
+      }),
+    ])
+
+    const msgDelta = events.find(e => e.type === 'message_delta') as any
+    // input_tokens = 34097 - 34048 = 49 (non-cached input only)
+    expect(msgDelta.usage.input_tokens).toBe(49)
+    expect(msgDelta.usage.cache_read_input_tokens).toBe(34048)
+    expect(msgDelta.usage.output_tokens).toBe(30)
+  })
 })

packages/@ant/model-provider/src/shared/openaiStreamAdapter.ts

@@ -13,10 +13,10 @@ import { randomUUID } from 'crypto'
  *   finish_reason            → message_delta(stop_reason) + message_stop
  *
  * Usage field mapping (OpenAI → Anthropic):
- *   prompt_tokens                        → input_tokens
- *   completion_tokens                    → output_tokens
- *   prompt_tokens_details.cached_tokens  → cache_read_input_tokens
- *   (no OpenAI equivalent)               → cache_creation_input_tokens (always 0)
+ *   prompt_tokens - cached_tokens             → input_tokens (non-cached input only)
+ *   completion_tokens                         → output_tokens
+ *   prompt_tokens_details.cached_tokens       → cache_read_input_tokens
+ *   (no OpenAI equivalent)                    → cache_creation_input_tokens (always 0)
  *
  *   All four fields are emitted in the post-loop message_delta (not message_start)
  *   so that trailing usage chunks (sent after finish_reason by some
@@ -54,6 +54,9 @@ export async function* adaptOpenAIStreamToAnthropic(
   let textBlockOpen = false
 
   // Track usage — all four Anthropic fields, populated from OpenAI usage fields:
+  // rawInputTokens tracks the raw prompt_tokens (OpenAI total, including cached).
+  // inputTokens is the derived Anthropic value (non-cached only = rawInputTokens - cachedReadTokens).
+  let rawInputTokens = 0
   let inputTokens = 0
   let outputTokens = 0
   let cachedReadTokens = 0
@@ -71,12 +74,17 @@ export async function* adaptOpenAIStreamToAnthropic(
 
     // Extract usage from any chunk that carries it.
     if (chunk.usage) {
-      inputTokens = chunk.usage.prompt_tokens ?? inputTokens
+      rawInputTokens = chunk.usage.prompt_tokens ?? rawInputTokens
+      const rawCached =
+        ((chunk.usage as any).prompt_tokens_details?.cached_tokens as
+          | number
+          | undefined) ?? cachedReadTokens
+      // Anthropic's input_tokens = non-cached input only. OpenAI's prompt_tokens
+      // includes cached tokens, so subtract. Clamp to 0 in case cached > total
+      // due to a streaming race.
+      inputTokens = Math.max(0, rawInputTokens - rawCached)
       outputTokens = chunk.usage.completion_tokens ?? outputTokens
-      const details = (chunk.usage as any).prompt_tokens_details
-      if (details?.cached_tokens != null) {
-        cachedReadTokens = details.cached_tokens
-      }
+      cachedReadTokens = rawCached
     }
 
     // Emit message_start on first chunk

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/BashTool/toolName.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type BASH_TOOL_NAME = any
+/** Bash 工具在 API 与 Agent 提示串中的注册名称字面量（与 `@claude-code-best/builtin-tools` 中 `BASH_TOOL_NAME` 常量一致）。 */
+export type BASH_TOOL_NAME = 'Bash'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/ExitPlanModeTool/constants.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type EXIT_PLAN_MODE_TOOL_NAME = any
+/** ExitPlanMode 工具在 API 中的注册名称字面量（与内置 ExitPlanMode 工具 `name` 一致）。 */
+export type EXIT_PLAN_MODE_TOOL_NAME = 'ExitPlanMode'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileEditTool/constants.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type FILE_EDIT_TOOL_NAME = any
+/** Edit（文件编辑）工具在 API 中的注册名称字面量（与 `FILE_EDIT_TOOL_NAME` 常量 `'Edit'` 一致）。 */
+export type FILE_EDIT_TOOL_NAME = 'Edit'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileReadTool/prompt.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type FILE_READ_TOOL_NAME = any
+/** Read（文件读取）工具在 API 中的注册名称字面量（与 `FILE_READ_TOOL_NAME` 常量 `'Read'` 一致）。 */
+export type FILE_READ_TOOL_NAME = 'Read'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/FileWriteTool/prompt.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type FILE_WRITE_TOOL_NAME = any
+/** Write（文件写入）工具在 API 中的注册名称字面量（与 `FILE_WRITE_TOOL_NAME` 常量 `'Write'` 一致）。 */
+export type FILE_WRITE_TOOL_NAME = 'Write'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/GlobTool/prompt.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type GLOB_TOOL_NAME = any
+/** Glob（文件名模式匹配）工具在 API 中的注册名称字面量（与 `GLOB_TOOL_NAME` 常量 `'Glob'` 一致）。 */
+export type GLOB_TOOL_NAME = 'Glob'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/GrepTool/prompt.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type GREP_TOOL_NAME = any
+/** Grep（内容搜索）工具在 API 中的注册名称字面量（与 `GREP_TOOL_NAME` 常量 `'Grep'` 一致）。 */
+export type GREP_TOOL_NAME = 'Grep'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/NotebookEditTool/constants.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type NOTEBOOK_EDIT_TOOL_NAME = any
+/** NotebookEdit（笔记本单元格编辑）工具在 API 中的注册名称字面量（与 `NOTEBOOK_EDIT_TOOL_NAME` 常量一致）。 */
+export type NOTEBOOK_EDIT_TOOL_NAME = 'NotebookEdit'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/SendMessageTool/constants.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type SEND_MESSAGE_TOOL_NAME = any
+/** SendMessage（向用户/通道发消息）工具在 API 中的注册名称字面量（与 `SEND_MESSAGE_TOOL_NAME` 常量一致）。 */
+export type SEND_MESSAGE_TOOL_NAME = 'SendMessage'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/WebFetchTool/prompt.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type WEB_FETCH_TOOL_NAME = any
+/** WebFetch（拉取并处理 URL 内容）工具在 API 中的注册名称字面量（与 `WEB_FETCH_TOOL_NAME` 常量一致）。 */
+export type WEB_FETCH_TOOL_NAME = 'WebFetch'

packages/builtin-tools/src/tools/AgentTool/built-in/src/tools/WebSearchTool/prompt.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type WEB_SEARCH_TOOL_NAME = any
+/** WebSearch（联网搜索）工具在 API 中的注册名称字面量（与 `WEB_SEARCH_TOOL_NAME` 常量一致）。 */
+export type WEB_SEARCH_TOOL_NAME = 'WebSearch'

packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/auth.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type isUsing3PServices = any
+/** 是否正在使用第三方（非 Anthropic 直连）API 或服务；与仓库根 `src/utils/auth.ts` 中 `isUsing3PServices` 签名一致。 */
+export type isUsing3PServices = () => boolean // 返回 true 表示当前配置走兼容层或第三方模型端点

packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/embeddedTools.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type hasEmbeddedSearchTools = any
+/** 当前构建是否将 Glob/Grep 嵌入其它工具而不单独注册；与仓库根 `src/utils/embeddedTools.ts` 中 `hasEmbeddedSearchTools` 一致。 */
+export type hasEmbeddedSearchTools = () => boolean // 返回 true 时工具列表不包含独立的 Glob/Grep 工具名

packages/builtin-tools/src/tools/AgentTool/built-in/src/utils/settings/settings.ts

@@ -1,2 +1,4 @@
-// Auto-generated type stub — replace with real implementation
-export type getSettings_DEPRECATED = any
+import type { SettingsJson } from 'src/utils/settings/types.js'
+
+/** 返回各设置来源合并后的快照（已废弃函数名，行为同 `getInitialSettings`）；与 `src/utils/settings/settings.ts` 一致。 */
+export type getSettings_DEPRECATED = () => SettingsJson // 无参数；至少得到可空字段填充后的合并设置对象

packages/builtin-tools/src/tools/AgentTool/builtInAgents.ts

@@ -12,9 +12,7 @@ import type { AgentDefinition } from './loadAgentsDir.js'
 
 export function areExplorePlanAgentsEnabled(): boolean {
   if (feature('BUILTIN_EXPLORE_PLAN_AGENTS')) {
-    // 3P default: true — Bedrock/Vertex keep agents enabled (matches pre-experiment
-    // external behavior). A/B test treatment sets false to measure impact of removal.
-    return getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_stoat', true)
+    return true
   }
   return false
 }

packages/builtin-tools/src/tools/AgentTool/src/Tool.ts

@@ -1,4 +1,8 @@
-// Auto-generated type stub — replace with real implementation
-export type buildTool = any
-export type ToolDef = any
-export type toolMatchesName = any
+/** 根据工具定义装配宿主侧可调用 `Tool` 实例的工厂函数类型。 */
+export type buildTool = typeof import('src/Tool.js').buildTool
+
+/** 工具定义泛型（输入 Schema、权限、进度等）；与宿主 `ToolDef` 一致。 */
+export type ToolDef = import('src/Tool.js').ToolDef
+
+/** 判断工具主名称或别名是否与查询名称相等；与宿主 `toolMatchesName` 一致。 */
+export type toolMatchesName = typeof import('src/Tool.js').toolMatchesName

packages/builtin-tools/src/tools/AgentTool/src/components/ConfigurableShortcutHint.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type ConfigurableShortcutHint = any
+/** 可配置快捷键提示组件（从 keybindings 解析展示文案）；与宿主 `ConfigurableShortcutHint` 组件类型一致。 */
+export type ConfigurableShortcutHint =
+  typeof import('src/components/ConfigurableShortcutHint.js').ConfigurableShortcutHint

packages/builtin-tools/src/tools/AgentTool/src/components/CtrlOToExpand.ts

@@ -1,3 +1,7 @@
-// Auto-generated type stub — replace with real implementation
-export type CtrlOToExpand = any
-export type SubAgentProvider = any
+/** 「Ctrl+O 展开」提示组件；与宿主 `src/components/CtrlOToExpand.tsx` 中 `CtrlOToExpand` 一致。 */
+export type CtrlOToExpand =
+  typeof import('src/components/CtrlOToExpand.js').CtrlOToExpand
+
+/** 标记子 Agent 输出上下文，用于抑制重复的展开提示；与宿主 `SubAgentProvider` 一致。 */
+export type SubAgentProvider =
+  typeof import('src/components/CtrlOToExpand.js').SubAgentProvider

packages/builtin-tools/src/tools/AgentTool/src/components/design-system/Byline.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type Byline = any
+/** Ink 底部快捷键说明行容器组件；与 `@anthropic/ink` 导出的 `Byline` 一致。 */
+export type Byline = typeof import('@anthropic/ink').Byline

packages/builtin-tools/src/tools/AgentTool/src/components/design-system/KeyboardShortcutHint.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type KeyboardShortcutHint = any
+/** Ink 快捷键「按键 + 动作」展示组件；与 `@anthropic/ink` 导出的 `KeyboardShortcutHint` 一致。 */
+export type KeyboardShortcutHint =
+  typeof import('@anthropic/ink').KeyboardShortcutHint

packages/builtin-tools/src/tools/AgentTool/src/types/message.ts

@@ -1,3 +1,6 @@
-// Auto-generated type stub — replace with real implementation
-export type Message = any
-export type NormalizedUserMessage = any
+/** 对话消息联合类型（含用户/助手/系统等）；与宿主 `src/types/message.js` 重导出一致。 */
+export type Message = import('src/types/message.js').Message
+
+/** 归一化后的用户消息形状；与宿主 `src/types/message.js` 中 `NormalizedUserMessage` 一致。 */
+export type NormalizedUserMessage =
+  import('src/types/message.js').NormalizedUserMessage

packages/builtin-tools/src/tools/AgentTool/src/utils/debug.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type logForDebugging = any
+/** 写入调试日志文件（受日志级别与过滤规则约束）；与宿主 `src/utils/debug.js` 中 `logForDebugging` 一致。 */
+export type logForDebugging =
+  typeof import('src/utils/debug.js').logForDebugging

packages/builtin-tools/src/tools/AgentTool/src/utils/promptCategory.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getQuerySourceForAgent = any
+/** 按内置/自定义 Agent 类型解析用于遥测或分类的 `QuerySource`；与宿主 `getQuerySourceForAgent` 一致。 */
+export type getQuerySourceForAgent =
+  typeof import('src/utils/promptCategory.js').getQuerySourceForAgent

packages/builtin-tools/src/tools/AgentTool/src/utils/settings/constants.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type SettingSource = any
+/** 设置文件来源层级标识（用户/项目/本地等）；与宿主 `src/utils/settings/constants.js` 中 `SettingSource` 一致。 */
+export type SettingSource =
+  import('src/utils/settings/constants.js').SettingSource

packages/builtin-tools/src/tools/AskUserQuestionTool/src/bootstrap/state.ts

@@ -1,3 +1,7 @@
-// Auto-generated type stub — replace with real implementation
-export type getAllowedChannels = any
-export type getQuestionPreviewFormat = any
+/** 返回当前允许展示的通道列表（含名称、连接状态等）；与宿主 `src/bootstrap/state.js` 中 `getAllowedChannels` 一致。 */
+export type getAllowedChannels =
+  typeof import('src/bootstrap/state.js').getAllowedChannels
+
+/** 返回问题预览渲染格式（Markdown/HTML）或未配置；与宿主 `getQuestionPreviewFormat` 一致。 */
+export type getQuestionPreviewFormat =
+  typeof import('src/bootstrap/state.js').getQuestionPreviewFormat

packages/builtin-tools/src/tools/AskUserQuestionTool/src/components/MessageResponse.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type MessageResponse = any
+/** 工具结果在消息流中的外层布局组件；与宿主 `src/components/MessageResponse.js` 中 `MessageResponse` 一致。 */
+export type MessageResponse =
+  typeof import('src/components/MessageResponse.js').MessageResponse

packages/builtin-tools/src/tools/AskUserQuestionTool/src/constants/figures.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type BLACK_CIRCLE = any
+/** 列表/状态行中使用的实心圆点字符（平台相关）；与宿主 `src/constants/figures.js` 中 `BLACK_CIRCLE` 常量类型一致。 */
+export type BLACK_CIRCLE =
+  typeof import('src/constants/figures.js').BLACK_CIRCLE

packages/builtin-tools/src/tools/AskUserQuestionTool/src/utils/permissions/PermissionMode.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getModeColor = any
+/** 将权限模式映射为 Ink 主题颜色键，用于状态行等 UI；与宿主 `getModeColor` 一致。 */
+export type getModeColor =
+  typeof import('src/utils/permissions/PermissionMode.js').getModeColor

packages/builtin-tools/src/tools/BashTool/src/Tool.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type ToolPermissionContext = any
+/** 工具权限检查用的不可变上下文快照；与宿主 `src/Tool.js` 中 `ToolPermissionContext` 一致。 */
+export type ToolPermissionContext = import('src/Tool.js').ToolPermissionContext

packages/builtin-tools/src/tools/BashTool/src/bootstrap/state.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getOriginalCwd = any
+/** 返回进程启动时的原始工作目录（不受中途切换工作区影响）；与宿主 `getOriginalCwd` 一致。 */
+export type getOriginalCwd =
+  typeof import('src/bootstrap/state.js').getOriginalCwd

packages/builtin-tools/src/tools/BashTool/src/hooks/useCanUseTool.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type CanUseToolFn = any
+/** 工具调用权限判定回调（交互/自动模式分支）；与宿主 `src/hooks/useCanUseTool.tsx` 中 `CanUseToolFn` 一致。 */
+export type CanUseToolFn = import('src/hooks/useCanUseTool.js').CanUseToolFn

packages/builtin-tools/src/tools/BashTool/src/services/analytics/growthbook.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type getFeatureValue_CACHED_MAY_BE_STALE = any
+/** 从磁盘缓存读取 GrowthBook/门控配置（可能略旧）；与宿主 `getFeatureValue_CACHED_MAY_BE_STALE` 一致。 */
+export type getFeatureValue_CACHED_MAY_BE_STALE =
+  typeof import('src/services/analytics/growthbook.js').getFeatureValue_CACHED_MAY_BE_STALE

packages/builtin-tools/src/tools/BashTool/src/services/analytics/index.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type logEvent = any
+/** 同步记录分析事件（未附加 sink 时入队）；与宿主 `src/services/analytics/index.js` 中 `logEvent` 一致。 */
+export type logEvent = typeof import('src/services/analytics/index.js').logEvent

packages/builtin-tools/src/tools/BashTool/src/state/AppState.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type AppState = any
+/** REPL 全局 UI 与权限等状态快照类型；与宿主 `src/state/AppStateStore.js` 中 `AppState` 一致。 */
+export type AppState = import('src/state/AppStateStore.js').AppState

packages/builtin-tools/src/tools/BashTool/src/utils/Shell.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type setCwd = any
+/** 将 Shell 会话当前目录设为解析后的物理路径；与宿主 `src/utils/Shell.js` 中 `setCwd` 一致。 */
+export type setCwd = typeof import('src/utils/Shell.js').setCwd

packages/builtin-tools/src/tools/BashTool/src/utils/cwd.ts

@@ -1,2 +1,2 @@
-// Auto-generated type stub — replace with real implementation
-export type getCwd = any
+/** 返回当前 Shell/会话逻辑工作目录字符串；与宿主 `src/utils/cwd.js` 中 `getCwd` 一致。 */
+export type getCwd = typeof import('src/utils/cwd.js').getCwd

packages/builtin-tools/src/tools/BashTool/src/utils/permissions/filesystem.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type pathInAllowedWorkingPath = any
+/** 判断路径是否落在当前工具允许的合并工作目录内；与宿主 `pathInAllowedWorkingPath` 一致。 */
+export type pathInAllowedWorkingPath =
+  typeof import('src/utils/permissions/filesystem.js').pathInAllowedWorkingPath

packages/builtin-tools/src/tools/BashTool/src/utils/sandbox/sandbox-ui-utils.ts

@@ -1,2 +1,3 @@
-// Auto-generated type stub — replace with real implementation
-export type removeSandboxViolationTags = any
+/** 从展示文本中剥离沙箱违规相关的标记标签，避免 UI 噪音；与宿主 `removeSandboxViolationTags` 一致。 */
+export type removeSandboxViolationTags =
+  typeof import('src/utils/sandbox/sandbox-ui-utils.js').removeSandboxViolationTags

packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts

@@ -121,6 +121,29 @@ export const ExecuteTool = buildTool({
       }
     }
 
+    // Validate input before delegating — prevents crashes when the model
+    // omits required params (e.g. TeamCreate without team_name →
+    // sanitizeName(undefined).replace() TypeError).
+    if (targetTool.validateInput) {
+      const validation = await targetTool.validateInput(
+        input.params as Record<string, unknown>,
+        context,
+      )
+      if (!validation.result) {
+        return {
+          data: {
+            result: null,
+            tool_name: input.tool_name,
+          },
+          newMessages: [
+            createUserMessage({
+              content: `Invalid parameters for tool "${input.tool_name}": ${validation.message}`,
+            }),
+          ],
+        }
+      }
+    }
+
     // Check permissions on the target tool
     const permResult = await targetTool.checkPermissions?.(
       input.params as Record<string, unknown>,
@@ -164,7 +187,7 @@ export const ExecuteTool = buildTool({
     }
   },
   renderToolUseMessage(input) {
-    return `Executing ${input.tool_name}...`
+    return `${input.tool_name}`
   },
   userFacingName() {
     return 'ExecuteExtraTool'

packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts

@@ -1,12 +1,10 @@
 /**
  * ExecuteTool.test.ts
  *
- * Thin subprocess wrapper that runs the actual tests in an isolated bun:test
- * process. This prevents mock.module() leaks from other test files
- * (e.g., agentToolUtils.test.ts mocking src/Tool.js) from affecting
- * ExecuteTool's tests.
+ * 薄层子进程包装器，在独立的 bun:test 进程中运行实际测试。
+ * 这样可以防止其他测试文件的 mock.module() 漏出（例如 agentToolUtils.test.ts
+ * 对 src/Tool.js 的 mock）影响 ExecuteTool 的测试。
  */
-
 import { describe, test, expect } from 'bun:test'
 import { resolve, relative } from 'path'
 

packages/builtin-tools/src/tools/ExecuteTool/prompt.ts

@@ -4,16 +4,34 @@ export const DESCRIPTION =
   'ExecuteExtraTool — a first-class core tool that is always loaded and available. Execute any deferred tool by name with parameters. Use it after discovering a tool via SearchExtraTools. This is NOT a remote or external tool — it runs locally with full permissions.'
 
 export function getPrompt(): string {
-  return `ExecuteExtraTool — a first-class core tool, always loaded, always available in your tool list. Runs locally with full permissions — NOT a remote or external tool. You do NOT need to search for it.
+  return `ExecuteExtraTool — always loaded, always available. Runs locally with full permissions — NOT a remote or external tool.
 
-This tool accepts a tool_name and params object, looks up the target tool in the global tool registry, and delegates execution to it. The target tool runs with the same permissions and capabilities as if it were called directly.
+## What it does
+Accepts a tool_name and params, looks up the target tool in the registry, and delegates execution to it. The target tool runs with the same permissions as if called directly.
 
-When to use: After SearchExtraTools discovers a deferred tool name, call this tool with {"tool_name": "<name>", "params": {...}} to invoke it immediately.
-When NOT to use: For core tools already in your tool list (Read, Edit, Write, Bash, Glob, Grep, Agent, WebFetch, WebSearch, Skill, etc.) — call those directly.
+## When to use
+ONLY for deferred tools discovered via SearchExtraTools. Core tools (Read, Edit, Write, Bash, Glob, Grep, Agent, WebFetch, WebSearch, Skill) are always in your tool list — call them directly, NOT through ExecuteExtraTool.
 
-Inputs:
-- tool_name: The exact name of the target tool (string)
-- params: The parameters to pass to the target tool (object)
+## How to call — two-step workflow
 
-If the tool is not found, an error message will be returned suggesting to use SearchExtraTools to discover available tools.`
+Step 1: SearchExtraTools discovers the tool name and schema.
+Step 2: This tool executes it.
+
+Example — user asks to schedule a cron job:
+  SearchExtraTools({"query": "select:CronCreate"})
+  → Response: "Found deferred tool(s): CronCreate"
+  ExecuteExtraTool({"tool_name": "CronCreate", "params": {"schedule": "*/5 * * * *", "prompt": "check deploy"}})
+  → Response: Cron job created
+
+Example — MCP tool:
+  SearchExtraTools({"query": "select:mcp__slack__send_message"})
+  → Response: "Found deferred tool(s): mcp__slack__send_message"
+  ExecuteExtraTool({"tool_name": "mcp__slack__send_message", "params": {"channel": "C123", "text": "hello"}})
+
+## Inputs
+- tool_name: Exact name of the target tool (string, e.g. "CronCreate", "mcp__slack__send_message")
+- params: Object with the target tool's parameters. Check the tool's schema from SearchExtraTools discover: response.
+
+## Failure handling
+If this tool returns an error, do NOT retry or re-search. Tell the user what failed and suggest alternatives.`
 }

packages/builtin-tools/src/tools/FileEditTool/FileEditTool.ts

@@ -70,7 +70,6 @@ import {
   areFileEditsInputsEquivalent,
   findActualString,
   getPatchForEdit,
-  preserveQuoteStyle,
 } from './utils.js'
 
 // V8/Bun string length limit is ~2^30 characters (~1 billion). For typical
@@ -297,7 +296,7 @@ export const FileEditTool = buildTool({
 
     const file = fileContent
 
-    // Use findActualString to handle quote normalization
+    // Use findActualString to find exact match
     const actualOldString = findActualString(file, old_string)
     if (!actualOldString) {
       return {
@@ -452,23 +451,16 @@ export const FileEditTool = buildTool({
       }
     }
 
-    // 3. Use findActualString to handle quote normalization
+    // 3. Find the exact string in file content
     const actualOldString =
       findActualString(originalFileContents, old_string) || old_string
 
-    // Preserve curly quotes in new_string when the file uses them
-    const actualNewString = preserveQuoteStyle(
-      old_string,
-      actualOldString,
-      new_string,
-    )
-
     // 4. Generate patch
     const { patch, updatedFile } = getPatchForEdit({
       filePath: absoluteFilePath,
       fileContents: originalFileContents,
       oldString: actualOldString,
-      newString: actualNewString,
+      newString: new_string,
       replaceAll: replace_all,
     })
 

packages/builtin-tools/src/tools/FileEditTool/UI.tsx

@@ -20,7 +20,7 @@ import { readEditContext } from 'src/utils/readEditContext.js';
 import { firstLineOf } from 'src/utils/stringUtils.js';
 import type { ThemeName } from 'src/utils/theme.js';
 import type { FileEditOutput } from './types.js';
-import { findActualString, getPatchForEdit, preserveQuoteStyle } from './utils.js';
+import { findActualString, getPatchForEdit } from './utils.js';
 
 export function userFacingName(
   input:
@@ -265,12 +265,11 @@ async function loadRejectionDiff(
       return { patch, firstLine: null, fileContent: undefined };
     }
     const actualOld = findActualString(ctx.content, oldString) || oldString;
-    const actualNew = preserveQuoteStyle(oldString, actualOld, newString);
     const { patch } = getPatchForEdit({
       filePath,
       fileContents: ctx.content,
       oldString: actualOld,
-      newString: actualNew,
+      newString: newString,
       replaceAll,
     });
     return {

packages/builtin-tools/src/tools/FileEditTool/__tests__/utils.test.ts

@@ -4,45 +4,8 @@ import { logMock } from '../../../../../../tests/mocks/log'
 // Mock log.ts to cut the heavy dependency chain
 mock.module('src/utils/log.ts', logMock)
 
-const {
-  normalizeQuotes,
-  stripTrailingWhitespace,
-  findActualString,
-  preserveQuoteStyle,
-  applyEditToFile,
-  LEFT_SINGLE_CURLY_QUOTE,
-  RIGHT_SINGLE_CURLY_QUOTE,
-  LEFT_DOUBLE_CURLY_QUOTE,
-  RIGHT_DOUBLE_CURLY_QUOTE,
-} = await import('../utils')
-
-// ─── normalizeQuotes ────────────────────────────────────────────────────
-
-describe('normalizeQuotes', () => {
-  test('converts left single curly to straight', () => {
-    expect(normalizeQuotes(`${LEFT_SINGLE_CURLY_QUOTE}hello`)).toBe("'hello")
-  })
-
-  test('converts right single curly to straight', () => {
-    expect(normalizeQuotes(`hello${RIGHT_SINGLE_CURLY_QUOTE}`)).toBe("hello'")
-  })
-
-  test('converts left double curly to straight', () => {
-    expect(normalizeQuotes(`${LEFT_DOUBLE_CURLY_QUOTE}hello`)).toBe('"hello')
-  })
-
-  test('converts right double curly to straight', () => {
-    expect(normalizeQuotes(`hello${RIGHT_DOUBLE_CURLY_QUOTE}`)).toBe('hello"')
-  })
-
-  test('leaves straight quotes unchanged', () => {
-    expect(normalizeQuotes('\'hello\' "world"')).toBe('\'hello\' "world"')
-  })
-
-  test('handles empty string', () => {
-    expect(normalizeQuotes('')).toBe('')
-  })
-})
+const { stripTrailingWhitespace, findActualString, applyEditToFile } =
+  await import('../utils')
 
 // ─── stripTrailingWhitespace ────────────────────────────────────────────
 
@@ -91,12 +54,6 @@ describe('findActualString', () => {
     expect(findActualString('hello world', 'hello')).toBe('hello')
   })
 
-  test('finds match with curly quotes normalized', () => {
-    const fileContent = `${LEFT_DOUBLE_CURLY_QUOTE}hello${RIGHT_DOUBLE_CURLY_QUOTE}`
-    const result = findActualString(fileContent, '"hello"')
-    expect(result).not.toBeNull()
-  })
-
   test('returns null when not found', () => {
     expect(findActualString('hello world', 'xyz')).toBeNull()
   })
@@ -107,124 +64,13 @@ describe('findActualString', () => {
     expect(result).toBe('')
   })
 
-  // ── Tab/space normalization (Bug #2 reproduction) ──
-
-  test('finds match when search uses spaces but file uses tabs', () => {
-    // File content uses Tab indentation
-    const fileContent = '\tif (x) {\n\t\treturn 1;\n\t}'
-    // User copies from Read output which renders tabs as spaces
-    const searchWithSpaces = '    if (x) {\n        return 1;\n    }'
-    const result = findActualString(fileContent, searchWithSpaces)
-    expect(result).not.toBeNull()
-    expect(result).toBe(fileContent)
-  })
-
-  test('finds match when search mixes tabs and spaces inconsistently', () => {
-    const fileContent = '\tconst x = 1; // comment'
-    const searchMixed = '    const x = 1; // comment'
-    const result = findActualString(fileContent, searchMixed)
-    expect(result).not.toBeNull()
-  })
-
-  test('finds match for single-line tab-to-space mismatch', () => {
-    const fileContent = '\t\torder_price = NormalizeDouble(ask, digits);'
-    const searchSpaces = '        order_price = NormalizeDouble(ask, digits);'
-    const result = findActualString(fileContent, searchSpaces)
-    expect(result).not.toBeNull()
-  })
-
-  // ── CJK / UTF-8 characters (Bug #1 reproduction) ──
+  // ── CJK / UTF-8 characters ──
 
   test('finds match with CJK characters in content', () => {
     const fileContent = 'input int x = 620; // 止盈点数(点) — 32个pip=320点'
     const result = findActualString(fileContent, fileContent)
     expect(result).toBe(fileContent)
   })
-
-  test('finds match with CJK characters when tab/space differs', () => {
-    const fileContent = '\t// 向上突破 → Sell Limit (逆方向做空)'
-    const searchSpaces = '    // 向上突破 → Sell Limit (逆方向做空)'
-    const result = findActualString(fileContent, searchSpaces)
-    expect(result).not.toBeNull()
-    expect(result).toBe(fileContent)
-  })
-
-  // ── Multiline with tabs + CJK (combined Bug #1 + #2) ──
-
-  test('finds multiline match with tabs and CJK characters', () => {
-    const fileContent =
-      '\tif(effective_dir == BREAKOUT_UP)\n\t\t{\n\t\t\t// 向上突破\n\t\t}'
-    const searchSpaces =
-      '    if(effective_dir == BREAKOUT_UP)\n        {\n            // 向上突破\n        }'
-    const result = findActualString(fileContent, searchSpaces)
-    expect(result).not.toBeNull()
-    expect(result).toBe(fileContent)
-  })
-
-  // ── Returned string must be a valid substring of fileContent ──
-
-  test('returned string from tab match is a real substring of fileContent', () => {
-    const fileContent = 'prefix\n\t\tindented code\nsuffix'
-    const searchSpaces = 'prefix\n        indented code\nsuffix'
-    const result = findActualString(fileContent, searchSpaces)
-    expect(result).not.toBeNull()
-    expect(fileContent.includes(result!)).toBe(true)
-  })
-
-  test('returned string from partial tab match is a real substring', () => {
-    const fileContent = 'line1\n\tif (x) {\n\t\tdoStuff();\n\t}\nline5'
-    const searchSpaces = '    if (x) {\n        doStuff();\n    }'
-    const result = findActualString(fileContent, searchSpaces)
-    expect(result).not.toBeNull()
-    expect(fileContent.includes(result!)).toBe(true)
-  })
-
-  test('tab match with mixed indentation levels', () => {
-    const fileContent =
-      'class Foo {\n\t\tmethod1() {\n\t\t\treturn 42;\n\t\t}\n}'
-    const searchSpaces =
-      'class Foo {\n        method1() {\n            return 42;\n        }\n}'
-    const result = findActualString(fileContent, searchSpaces)
-    expect(result).not.toBeNull()
-    expect(fileContent.includes(result!)).toBe(true)
-  })
-})
-
-// ─── preserveQuoteStyle ─────────────────────────────────────────────────
-
-describe('preserveQuoteStyle', () => {
-  test('returns newString unchanged when no normalization happened', () => {
-    expect(preserveQuoteStyle('hello', 'hello', 'world')).toBe('world')
-  })
-
-  test('converts straight double quotes to curly in replacement', () => {
-    const oldString = '"hello"'
-    const actualOldString = `${LEFT_DOUBLE_CURLY_QUOTE}hello${RIGHT_DOUBLE_CURLY_QUOTE}`
-    const newString = '"world"'
-    const result = preserveQuoteStyle(oldString, actualOldString, newString)
-    expect(result).toContain(LEFT_DOUBLE_CURLY_QUOTE)
-    expect(result).toContain(RIGHT_DOUBLE_CURLY_QUOTE)
-  })
-
-  test('converts straight single quotes to curly in replacement', () => {
-    const oldString = "'hello'"
-    const actualOldString = `${LEFT_SINGLE_CURLY_QUOTE}hello${RIGHT_SINGLE_CURLY_QUOTE}`
-    const newString = "'world'"
-    const result = preserveQuoteStyle(oldString, actualOldString, newString)
-    expect(result).toContain(LEFT_SINGLE_CURLY_QUOTE)
-    expect(result).toContain(RIGHT_SINGLE_CURLY_QUOTE)
-  })
-
-  test('treats apostrophe in contraction as right curly quote', () => {
-    const oldString = "'it's a test'"
-    const actualOldString = `${LEFT_SINGLE_CURLY_QUOTE}it${RIGHT_SINGLE_CURLY_QUOTE}s a test${RIGHT_SINGLE_CURLY_QUOTE}`
-    const newString = "'don't worry'"
-    const result = preserveQuoteStyle(oldString, actualOldString, newString)
-    // The leading ' at position 0 should be LEFT_SINGLE_CURLY_QUOTE
-    expect(result[0]).toBe(LEFT_SINGLE_CURLY_QUOTE)
-    // The apostrophe in "don't" (between n and t) should be RIGHT_SINGLE_CURLY_QUOTE
-    expect(result).toContain(RIGHT_SINGLE_CURLY_QUOTE)
-  })
 })
 
 // ─── applyEditToFile ────────────────────────────────────────────────────

packages/builtin-tools/src/tools/FileEditTool/utils.ts

@@ -15,27 +15,6 @@ import {
 } from 'src/utils/file.js'
 import type { EditInput, FileEdit } from './types.js'
 
-// Claude can't output curly quotes, so we define them as constants here for Claude to use
-// in the code. We do this because we normalize curly quotes to straight quotes
-// when applying edits.
-export const LEFT_SINGLE_CURLY_QUOTE = '‘'
-export const RIGHT_SINGLE_CURLY_QUOTE = '’'
-export const LEFT_DOUBLE_CURLY_QUOTE = '“'
-export const RIGHT_DOUBLE_CURLY_QUOTE = '”'
-
-/**
- * Normalizes quotes in a string by converting curly quotes to straight quotes
- * @param str The string to normalize
- * @returns The string with all curly quotes replaced by straight quotes
- */
-export function normalizeQuotes(str: string): string {
-  return str
-    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
-    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
-    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
-    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"')
-}
-
 /**
  * Strips trailing whitespace from each line in a string while preserving line endings
  * @param str The string to process
@@ -64,261 +43,22 @@ export function stripTrailingWhitespace(str: string): string {
 }
 
 /**
- * Normalizes whitespace for fuzzy matching by converting tabs to spaces
- * and collapsing leading whitespace on each line to a canonical form.
- * This handles the case where Read tool output renders tabs as spaces,
- * so users copy spaces from the output but the file actually has tabs.
- */
-function normalizeWhitespace(str: string): string {
-  return str.replace(/\t/g, '    ')
-}
-
-/**
- * Finds the actual string in the file content that matches the search string,
- * accounting for quote normalization and tab/space differences.
- *
- * Matching cascade:
- * 1. Exact match
- * 2. Quote normalization (curly → straight quotes)
- * 3. Tab/space normalization (tabs ↔ spaces in leading whitespace)
- * 4. Quote + tab/space normalization combined
+ * Finds the exact string in the file content.
  *
  * @param fileContent The file content to search in
  * @param searchString The string to search for
- * @returns The actual string found in the file, or null if not found
+ * @returns The search string if found, or null if not found
  */
 export function findActualString(
   fileContent: string,
   searchString: string,
 ): string | null {
-  // First try exact match
   if (fileContent.includes(searchString)) {
     return searchString
   }
-
-  // Try with normalized quotes
-  const normalizedSearch = normalizeQuotes(searchString)
-  const normalizedFile = normalizeQuotes(fileContent)
-
-  const searchIndex = normalizedFile.indexOf(normalizedSearch)
-  if (searchIndex !== -1) {
-    // Find the actual string in the file that matches
-    return fileContent.substring(searchIndex, searchIndex + searchString.length)
-  }
-
-  // Try with tab/space normalization — handles the case where Read output
-  // renders tabs as spaces and the user copies the rendered version
-  const wsNormalizedFile = normalizeWhitespace(fileContent)
-  const wsNormalizedSearch = normalizeWhitespace(searchString)
-
-  const wsSearchIndex = wsNormalizedFile.indexOf(wsNormalizedSearch)
-  if (wsSearchIndex !== -1) {
-    // Map the match position back to the original file content.
-    // We need to find the corresponding range in the original string.
-    return mapNormalizedMatchBackToFile(
-      fileContent,
-      wsNormalizedFile,
-      wsSearchIndex,
-      wsNormalizedSearch.length,
-    )
-  }
-
-  // Try combined: quote normalization + tab/space normalization
-  const combinedFile = normalizeWhitespace(normalizedFile)
-  const combinedSearch = normalizeWhitespace(normalizedSearch)
-
-  const combinedIndex = combinedFile.indexOf(combinedSearch)
-  if (combinedIndex !== -1) {
-    return mapNormalizedMatchBackToFile(
-      fileContent,
-      combinedFile,
-      combinedIndex,
-      combinedSearch.length,
-    )
-  }
-
   return null
 }
 
-/**
- * Given a match found in a normalized version of fileContent, map the match
- * position back to the original fileContent and extract the corresponding
- * substring.
- *
- * Strategy: walk through both strings character by character, building a
- * mapping from normalized offset to original offset. When a tab is expanded
- * to 4 spaces in the normalized version, the normalized offset advances by 4
- * while the original offset advances by 1.
- */
-function mapNormalizedMatchBackToFile(
-  fileContent: string,
-  normalizedFile: string,
-  normalizedStart: number,
-  normalizedLength: number,
-): string {
-  // Build a sparse mapping from normalized position → original position.
-  // We only need to map the range [normalizedStart, normalizedStart + normalizedLength].
-  let normPos = 0
-  let origPos = 0
-  let origStart = -1
-  let origEnd = -1
-
-  while (
-    origPos < fileContent.length &&
-    normPos <= normalizedStart + normalizedLength
-  ) {
-    if (normPos === normalizedStart) {
-      origStart = origPos
-    }
-    if (normPos === normalizedStart + normalizedLength) {
-      origEnd = origPos
-      break
-    }
-
-    const origChar = fileContent[origPos]!
-    if (origChar === '\t') {
-      // Tab expands to 4 spaces in normalized version
-      const nextNormPos = normPos + 4
-      // If normalizedStart falls within this expanded tab, snap to origPos
-      if (
-        normPos < normalizedStart &&
-        nextNormPos > normalizedStart &&
-        origStart === -1
-      ) {
-        origStart = origPos
-      }
-      if (
-        normPos < normalizedStart + normalizedLength &&
-        nextNormPos > normalizedStart + normalizedLength &&
-        origEnd === -1
-      ) {
-        origEnd = origPos + 1
-      }
-      normPos = nextNormPos
-      origPos++
-    } else {
-      normPos++
-      origPos++
-    }
-  }
-
-  // Fallback: if we couldn't map precisely, use character-count heuristic
-  if (origStart === -1) origStart = 0
-  if (origEnd === -1) {
-    // Approximate: use the ratio of original to normalized length
-    const ratio = fileContent.length / normalizedFile.length
-    origEnd = Math.round(origStart + normalizedLength * ratio)
-  }
-
-  return fileContent.substring(origStart, origEnd)
-}
-
-/**
- * When old_string matched via quote normalization (curly quotes in file,
- * straight quotes from model), apply the same curly quote style to new_string
- * so the edit preserves the file's typography.
- *
- * Uses a simple open/close heuristic: a quote character preceded by whitespace,
- * start of string, or opening punctuation is treated as an opening quote;
- * otherwise it's a closing quote.
- */
-export function preserveQuoteStyle(
-  oldString: string,
-  actualOldString: string,
-  newString: string,
-): string {
-  // If they're the same, no normalization happened
-  if (oldString === actualOldString) {
-    return newString
-  }
-
-  // Detect which curly quote types were in the file
-  const hasDoubleQuotes =
-    actualOldString.includes(LEFT_DOUBLE_CURLY_QUOTE) ||
-    actualOldString.includes(RIGHT_DOUBLE_CURLY_QUOTE)
-  const hasSingleQuotes =
-    actualOldString.includes(LEFT_SINGLE_CURLY_QUOTE) ||
-    actualOldString.includes(RIGHT_SINGLE_CURLY_QUOTE)
-
-  if (!hasDoubleQuotes && !hasSingleQuotes) {
-    return newString
-  }
-
-  let result = newString
-
-  if (hasDoubleQuotes) {
-    result = applyCurlyDoubleQuotes(result)
-  }
-  if (hasSingleQuotes) {
-    result = applyCurlySingleQuotes(result)
-  }
-
-  return result
-}
-
-function isOpeningContext(chars: string[], index: number): boolean {
-  if (index === 0) {
-    return true
-  }
-  const prev = chars[index - 1]
-  return (
-    prev === ' ' ||
-    prev === '\t' ||
-    prev === '\n' ||
-    prev === '\r' ||
-    prev === '(' ||
-    prev === '[' ||
-    prev === '{' ||
-    prev === '\u2014' || // em dash
-    prev === '\u2013' // en dash
-  )
-}
-
-function applyCurlyDoubleQuotes(str: string): string {
-  const chars = [...str]
-  const result: string[] = []
-  for (let i = 0; i < chars.length; i++) {
-    if (chars[i] === '"') {
-      result.push(
-        isOpeningContext(chars, i)
-          ? LEFT_DOUBLE_CURLY_QUOTE
-          : RIGHT_DOUBLE_CURLY_QUOTE,
-      )
-    } else {
-      result.push(chars[i]!)
-    }
-  }
-  return result.join('')
-}
-
-function applyCurlySingleQuotes(str: string): string {
-  const chars = [...str]
-  const result: string[] = []
-  for (let i = 0; i < chars.length; i++) {
-    if (chars[i] === "'") {
-      // Don't convert apostrophes in contractions (e.g., "don't", "it's")
-      // An apostrophe between two letters is a contraction, not a quote
-      const prev = i > 0 ? chars[i - 1] : undefined
-      const next = i < chars.length - 1 ? chars[i + 1] : undefined
-      const prevIsLetter = prev !== undefined && /\p{L}/u.test(prev)
-      const nextIsLetter = next !== undefined && /\p{L}/u.test(next)
-      if (prevIsLetter && nextIsLetter) {
-        // Apostrophe in a contraction — use right single curly quote
-        result.push(RIGHT_SINGLE_CURLY_QUOTE)
-      } else {
-        result.push(
-          isOpeningContext(chars, i)
-            ? LEFT_SINGLE_CURLY_QUOTE
-            : RIGHT_SINGLE_CURLY_QUOTE,
-        )
-      }
-    } else {
-      result.push(chars[i]!)
-    }
-  }
-  return result.join('')
-}
-
 /**
  * Transform edits to ensure replace_all always has a boolean value
  * @param edits Array of edits with optional replace_all

packages/builtin-tools/src/tools/NotebookEditTool/NotebookEditTool.ts

@@ -383,8 +383,8 @@ export const NotebookEditTool = buildTool({
       const language = notebook.metadata.language_info?.name ?? 'python'
       let new_cell_id
       if (
-        notebook.nbformat > 4 ||
-        (notebook.nbformat === 4 && notebook.nbformat_minor >= 5)
+        (notebook.nbformat ?? 4) > 4 ||
+        ((notebook.nbformat ?? 4) === 4 && (notebook.nbformat_minor ?? 0) >= 5)
       ) {
         if (edit_mode === 'insert') {
           new_cell_id = Math.random().toString(36).substring(2, 15)

packages/builtin-tools/src/tools/SearchExtraToolsTool/prompt.ts

@@ -25,13 +25,39 @@ function getToolLocationHint(): string {
 
 const PROMPT_TAIL = ` Returns matching tool names.
 
-IMPORTANT: ExecuteExtraTool is always available in your tool list. After this search returns tool names, you MUST call ExecuteExtraTool with {"tool_name": "<returned_name>", "params": {...}} to invoke the deferred tool. This is the ONLY way to execute deferred tools — do not read source code or analyze whether the tool is callable, just use ExecuteExtraTool directly.
+## Two-step workflow (MUST follow exactly)
 
-Query forms:
-- "select:CronCreate,Snip" — fetch these exact tools by name
-- "discover:schedule cron job" — pure discovery, returns tool info (name, description) without loading. Use when you want to understand available tools before deciding which to invoke.
+Deferred tools CANNOT be called directly. You MUST use this two-step pattern:
+
+Step 1 — Search: Call this tool (SearchExtraTools) to discover the target tool.
+  Input: {"query": "select:CronCreate"}
+  Response: "Found 1 deferred tool(s): CronCreate. Use ExecuteExtraTool with {"tool_name": "<name>", "params": {...}} to invoke."
+
+Step 2 — Execute: Call ExecuteExtraTool to run the discovered tool.
+  Input: {"tool_name": "CronCreate", "params": {"schedule": "*/5 * * * *", "prompt": "check the deploy"}}
+  Response: the actual tool result.
+
+## Example: user asks "schedule a cron to check deploy every 5 minutes"
+
+1. SearchExtraTools({"query": "select:CronCreate"})
+   → Response: Found deferred tool CronCreate
+2. ExecuteExtraTool({"tool_name": "CronCreate", "params": {"schedule": "*/5 * * * *", "prompt": "check the deploy"}})
+   → Response: Cron job created successfully
+
+If you don't know the exact tool name, use keyword search first:
+1. SearchExtraTools({"query": "cron schedule"})
+   → Response: Found deferred tool(s): CronCreate
+2. ExecuteExtraTool({"tool_name": "CronCreate", "params": {...}})
+
+## Query forms
+- "select:CronCreate" — exact tool name (fastest, preferred when you know the name from <available-deferred-tools>)
+- "select:CronCreate,CronList" — comma-separated multi-select
+- "discover:schedule cron job" — returns tool name + description + schema without loading. Use to understand a tool before calling it.
 - "notebook jupyter" — keyword search, up to max_results best matches
-- "+slack send" — require "slack" in the name, rank by remaining terms`
+- "+slack send" — require "slack" in the name, rank by remaining terms
+
+## Failure policy
+If ExecuteExtraTool fails, do NOT re-search for the same tool — it will loop. Stop and tell the user what failed.`
 
 /**
  * Check if a tool should be deferred (requires SearchExtraTools to load).

scripts/post-build.ts

@@ -9,28 +9,52 @@
 import { readdir, readFile, writeFile, cp } from 'node:fs/promises'
 import { chmodSync } from 'node:fs'
 import { join } from 'node:path'
-import { execSync } from 'node:child_process'
 
 const outdir = 'dist'
 
 async function postBuild() {
-  // Step 1: Patch globalThis.Bun destructuring in the single bundled file
-  const cliPath = join(outdir, 'cli.js')
+  // Step 1: Patch globalThis.Bun destructuring in ALL output files
   const BUN_DESTRUCTURE = /var \{([^}]+)\} = globalThis\.Bun;?/g
   const BUN_DESTRUCTURE_SAFE =
     'var {$1} = typeof globalThis.Bun !== "undefined" ? globalThis.Bun : {};'
 
   let bunPatched = 0
-  {
-    const content = await readFile(cliPath, 'utf-8')
+  const files = await readdir(outdir)
+  const jsFiles = files.filter(f => f.endsWith('.js'))
+
+  for (const file of jsFiles) {
+    const filePath = join(outdir, file)
+    const content = await readFile(filePath, 'utf-8')
+    BUN_DESTRUCTURE.lastIndex = 0
     if (BUN_DESTRUCTURE.test(content)) {
       await writeFile(
-        cliPath,
+        filePath,
         content.replace(BUN_DESTRUCTURE, BUN_DESTRUCTURE_SAFE),
       )
       bunPatched++
     }
+  }
+
+  // Also patch chunk files in dist/chunks/
+  const chunksDir = join(outdir, 'chunks')
+  let chunkFiles: string[] = []
+  try {
+    chunkFiles = (await readdir(chunksDir)).filter(f => f.endsWith('.js'))
+  } catch {
+    // No chunks directory — single-file build fallback
+  }
+
+  for (const file of chunkFiles) {
+    const filePath = join(chunksDir, file)
+    const content = await readFile(filePath, 'utf-8')
     BUN_DESTRUCTURE.lastIndex = 0
+    if (BUN_DESTRUCTURE.test(content)) {
+      await writeFile(
+        filePath,
+        content.replace(BUN_DESTRUCTURE, BUN_DESTRUCTURE_SAFE),
+      )
+      bunPatched++
+    }
   }
 
   // Step 2: Copy native addon files
@@ -55,7 +79,7 @@ async function postBuild() {
   chmodSync(cliNode, 0o755)
 
   console.log(
-    `Post-build complete: patched ${bunPatched} Bun destructure, generated entry points`,
+    `Post-build complete: patched ${bunPatched} Bun destructure across ${jsFiles.length + chunkFiles.length} files, generated entry points`,
   )
 }
 

src/buddy/companionReact.ts

@@ -73,7 +73,7 @@ function isAddressed(messages: Message[], name: string): boolean {
   ) {
     const m = messages[i]
     if (m?.type !== 'user') continue
-    const content = (m as any).message?.content
+    const content = m.message?.content
     if (typeof content === 'string' && pattern.test(content)) return true
   }
   return false
@@ -89,7 +89,7 @@ function buildTranscript(messages: Message[]): string {
     .filter(m => m.type === 'user' || m.type === 'assistant')
     .map(m => {
       const role = m.type === 'user' ? 'user' : 'claude'
-      const content = (m as any).message?.content
+      const content = m.message?.content
       const text =
         typeof content === 'string'
           ? content.slice(0, 300)

src/cli/print.ts

@@ -377,9 +377,6 @@ const cronJitterConfigModule =
   require('../utils/cronJitterConfig.js') as typeof import('../utils/cronJitterConfig.js')
 const cronGate =
   require('@claude-code-best/builtin-tools/tools/ScheduleCronTool/prompt.js') as typeof import('@claude-code-best/builtin-tools/tools/ScheduleCronTool/prompt.js')
-const extractMemoriesModule = feature('EXTRACT_MEMORIES')
-  ? (require('../services/extractMemories/extractMemories.js') as typeof import('../services/extractMemories/extractMemories.js'))
-  : null
 /* eslint-enable @typescript-eslint/no-require-imports */
 
 const SHUTDOWN_TEAM_PROMPT = `<system-reminder>
@@ -985,7 +982,14 @@ export async function runHeadless(
   // the forked agent mid-flight. Gated by isExtractModeActive so the
   // tengu_slate_thimble flag controls non-interactive extraction end-to-end.
   if (feature('EXTRACT_MEMORIES') && isExtractModeActive()) {
-    await extractMemoriesModule!.drainPendingExtraction()
+    try {
+      const { drainPendingExtraction } = await import(
+        '../services/extractMemories/extractMemories.js'
+      )
+      await drainPendingExtraction()
+    } catch {
+      // Module load failure — non-critical at shutdown
+    }
   }
 
   gracefulShutdownSync(
@@ -4962,7 +4966,7 @@ function handleChannelEnable(
   // channel messages queue at priority 'next' and are seen by the model on
   // the turn after they arrive.
   connection.client.setNotificationHandler(
-    ChannelMessageNotificationSchema(),
+    ChannelMessageNotificationSchema() as any,
     async notification => {
       const { content, meta } = notification.params
       logMCPDebug(
@@ -5038,7 +5042,7 @@ function reregisterChannelHandlerAfterReconnect(
     'Channel notifications re-registered after reconnect',
   )
   connection.client.setNotificationHandler(
-    ChannelMessageNotificationSchema(),
+    ChannelMessageNotificationSchema() as any,
     async notification => {
       const { content, meta } = notification.params
       logMCPDebug(

src/cli/transports/Transport.ts

@@ -1,2 +1,10 @@
-// Auto-generated stub — replace with real implementation
-export type Transport = any
+import type { StdoutMessage } from 'src/entrypoints/sdk/controlTypes.js'
+
+/** WebSocket / SSE+POST / Hybrid 等会话上行传输的共有接口。 */
+export type Transport = {
+  setOnData(callback: (data: string) => void): void // 注册下行数据回调（按行文本）
+  setOnClose(callback: (closeCode?: number) => void): void // 连接关闭时回调（可选关闭码）
+  connect(): void | Promise<void> // 建立或重连传输
+  write(message: StdoutMessage): void | Promise<void> // 向上游发送一条控制/流式消息
+  close(): void // 主动关闭并释放资源
+}

src/cli/transports/ccrClient.ts

@@ -381,7 +381,7 @@ export class CCRClient {
         if (!result.ok) {
           throw new RetryableError(
             'client event POST failed',
-            (result as any).retryAfterMs,
+            result.retryAfterMs,
           )
         }
       },
@@ -404,7 +404,7 @@ export class CCRClient {
         if (!result.ok) {
           throw new RetryableError(
             'internal event POST failed',
-            (result as any).retryAfterMs,
+            result.retryAfterMs,
           )
         }
       },
@@ -433,10 +433,7 @@ export class CCRClient {
           'delivery batch',
         )
         if (!result.ok) {
-          throw new RetryableError(
-            'delivery POST failed',
-            (result as any).retryAfterMs,
-          )
+          throw new RetryableError('delivery POST failed', result.retryAfterMs)
         }
       },
       baseDelayMs: 500,

src/cli/updateCCB.ts

@@ -9,9 +9,9 @@ import chalk from 'chalk'
 import { execSync } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
 import { logForDebugging } from '../utils/debug.js'
+import { distRoot } from '../utils/distRoot.js'
 import { execFileNoThrowWithCwd } from '../utils/execFileNoThrow.js'
 import { gracefulShutdown } from '../utils/gracefulShutdown.js'
 import { writeToStdout } from '../utils/process.js'
@@ -19,12 +19,9 @@ import { writeToStdout } from '../utils/process.js'
 const PACKAGE_NAME = 'claude-code-best'
 
 function getCurrentVersion(): string {
-  // Read version from the nearest package.json (walks up from this file)
+  // Read version from the nearest package.json (walks up from dist root)
   try {
-    const __dirname = dirname(fileURLToPath(import.meta.url))
-    // In dev: src/cli/updateCCB.ts → ../../package.json
-    // In build: dist/chunks/xxx.js → ../../package.json (may not exist)
-    const pkgPath = join(__dirname, '..', '..', 'package.json')
+    const pkgPath = join(distRoot, '..', 'package.json')
     if (existsSync(pkgPath)) {
       const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
       if (pkg.version) return pkg.version

src/commands.ts

@@ -19,6 +19,7 @@ import { context, contextNonInteractive } from './commands/context/index.js'
 import diff from './commands/diff/index.js'
 import doctor from './commands/doctor/index.js'
 import memory from './commands/memory/index.js'
+import mode from './commands/mode/index.js'
 import help from './commands/help/index.js'
 import ide from './commands/ide/index.js'
 import init from './commands/init.js'
@@ -327,6 +328,7 @@ const COMMANDS = memoize((): Command[] => [
   mcp,
   memory,
   mobile,
+  mode,
   model,
   outputStyle,
   remoteEnv,

src/commands/autofix-pr/__tests__/AutofixProgress.test.tsx

@@ -8,7 +8,7 @@ import * as React from 'react';
 import { renderToString } from '../../../utils/staticRender.js';
 import { AutofixProgress } from '../AutofixProgress.js';
 
-describe('AutofixProgress', () => {
+describe.skipIf(!!process.env.CI)('AutofixProgress', () => {
   test('renders target in header', async () => {
     const out = await renderToString(<AutofixProgress phase="detecting" target="acme/myrepo#42" />);
     expect(out).toContain('acme/myrepo#42');

src/commands/autofix-pr/__tests__/extractAutofixResult.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from 'bun:test'
+import type { SDKMessage } from '../../../entrypoints/agentSdkTypes.js'
+import {
+  AUTOFIX_RESULT_TAG,
+  extractAutofixResultFromLog,
+} from '../extractAutofixResult.js'
+
+function hookProgressMessage(stdout: string): SDKMessage {
+  return {
+    type: 'system',
+    subtype: 'hook_progress',
+    stdout,
+  } as unknown as SDKMessage
+}
+
+function assistantTextMessage(text: string): SDKMessage {
+  return {
+    type: 'assistant',
+    message: {
+      content: [{ type: 'text', text }],
+    },
+  } as unknown as SDKMessage
+}
+
+const sampleTag = (summary: string): string =>
+  `<${AUTOFIX_RESULT_TAG}>
+  <pr-number>42</pr-number>
+  <commits-pushed>
+    <commit sha="abc123">${summary}</commit>
+  </commits-pushed>
+  <ci-status>green</ci-status>
+  <summary>${summary}</summary>
+</${AUTOFIX_RESULT_TAG}>`
+
+describe('extractAutofixResultFromLog', () => {
+  test('returns null on empty log', () => {
+    expect(extractAutofixResultFromLog([])).toBeNull()
+  })
+
+  test('returns null when no tag present', () => {
+    const log = [
+      assistantTextMessage('just some normal text without the tag'),
+      hookProgressMessage('hook output without tag'),
+    ]
+    expect(extractAutofixResultFromLog(log)).toBeNull()
+  })
+
+  test('extracts from hook stdout', () => {
+    const tag = sampleTag('fixed lint error')
+    const log = [hookProgressMessage(`prefix\n${tag}\nsuffix`)]
+    const result = extractAutofixResultFromLog(log)
+    expect(result).toBe(tag)
+  })
+
+  test('extracts from assistant text', () => {
+    const tag = sampleTag('typecheck fixed')
+    const log = [assistantTextMessage(`Done!\n${tag}`)]
+    expect(extractAutofixResultFromLog(log)).toBe(tag)
+  })
+
+  test('extracts from hook_response subtype too', () => {
+    const tag = sampleTag('via hook_response')
+    const log = [
+      {
+        type: 'system',
+        subtype: 'hook_response',
+        stdout: tag,
+      } as unknown as SDKMessage,
+    ]
+    expect(extractAutofixResultFromLog(log)).toBe(tag)
+  })
+
+  test('returns the latest tag when multiple appear in different messages', () => {
+    const older = sampleTag('older attempt')
+    const newer = sampleTag('newer attempt')
+    const log = [
+      assistantTextMessage(`first try\n${older}`),
+      assistantTextMessage(`retry\n${newer}`),
+    ]
+    expect(extractAutofixResultFromLog(log)).toBe(newer)
+  })
+
+  test('returns null when open tag exists but close tag is missing (truncated)', () => {
+    const log = [
+      assistantTextMessage(
+        `<${AUTOFIX_RESULT_TAG}>\n<summary>got cut off mid-write...`,
+      ),
+    ]
+    expect(extractAutofixResultFromLog(log)).toBeNull()
+  })
+
+  test('returns earlier complete tag when latest open tag is truncated within the same block', () => {
+    // Retry scenario: a full result was emitted, then a second result tag
+    // started but got cut off. We should surface the earlier complete pair
+    // rather than dropping the whole block.
+    const complete = sampleTag('earlier complete result')
+    const truncated = `<${AUTOFIX_RESULT_TAG}>\n<summary>truncated retry...`
+    const log = [assistantTextMessage(`${complete}\n${truncated}`)]
+    expect(extractAutofixResultFromLog(log)).toBe(complete)
+  })
+
+  test('walks backwards so hook stdout from later in log wins over earlier assistant text', () => {
+    const earlier = sampleTag('via assistant first')
+    const later = sampleTag('via hook later')
+    const log = [
+      assistantTextMessage(`some output\n${earlier}`),
+      hookProgressMessage(later),
+    ]
+    expect(extractAutofixResultFromLog(log)).toBe(later)
+  })
+
+  test('ignores tag-shaped strings that span across messages (no concatenation)', () => {
+    // Open tag in one message, close tag in another — should NOT be stitched.
+    const log = [
+      assistantTextMessage(`<${AUTOFIX_RESULT_TAG}>\n<summary>part 1`),
+      assistantTextMessage(`part 2</summary>\n</${AUTOFIX_RESULT_TAG}>`),
+    ]
+    expect(extractAutofixResultFromLog(log)).toBeNull()
+  })
+
+  test('extracts when assistant content is a string (not block array)', () => {
+    // Some SDK paths emit assistant content as a raw string instead of
+    // a content-block array. Current implementation skips those — verify
+    // graceful no-op rather than crash.
+    const log = [
+      {
+        type: 'assistant',
+        message: { content: sampleTag('string content') },
+      } as unknown as SDKMessage,
+    ]
+    expect(extractAutofixResultFromLog(log)).toBeNull()
+  })
+})

src/commands/autofix-pr/__tests__/launchAutofixPr.test.ts

@@ -46,7 +46,7 @@ mock.module('src/utils/teleport.js', () => ({
 }))
 
 const registerMock = mock(() => ({
-  taskId: 'task-abc',
+  taskId: 'framework-task-id',
   sessionId: 'session-123',
   cleanup: () => {},
 }))
@@ -56,14 +56,41 @@ const checkEligibilityMock = mock(() =>
 const getSessionUrlMock = mock(
   (id: string) => `https://claude.ai/session/${id}`,
 )
+const registerCompletionHookMock = mock<
+  (taskType: string, hook: (taskId: string, metadata?: unknown) => void) => void
+>(() => {})
+const registerCompletionCheckerMock = mock<
+  (
+    taskType: string,
+    checker: (metadata?: unknown) => Promise<string | null>,
+  ) => void
+>(() => {})
+const registerContentExtractorMock = mock<
+  (taskType: string, extractor: (log: unknown[]) => string | null) => void
+>(() => {})
 
 mock.module('src/tasks/RemoteAgentTask/RemoteAgentTask.js', () => ({
   checkRemoteAgentEligibility: checkEligibilityMock,
   registerRemoteAgentTask: registerMock,
+  registerCompletionHook: registerCompletionHookMock,
+  registerCompletionChecker: registerCompletionCheckerMock,
+  registerContentExtractor: registerContentExtractorMock,
   getRemoteTaskSessionUrl: getSessionUrlMock,
   formatPreconditionError: (e: { type: string }) => e.type,
 }))
 
+const fetchPrHeadShaMock = mock<
+  (owner: string, repo: string, prNumber: number) => Promise<string | null>
+>(() => Promise.resolve('sha-baseline-abc123'))
+
+// Mock prFetch.ts (gh CLI spawn layer) — keeping the pure decision matrix
+// in prOutcomeCheck.ts unmocked so its tests are unaffected by this file's
+// process-global mock.module pollution.
+mock.module('src/commands/autofix-pr/prFetch.js', () => ({
+  fetchPrHeadSha: fetchPrHeadShaMock,
+  checkPrAutofixOutcome: mock(() => Promise.resolve({ completed: false })),
+}))
+
 const detectRepoMock = mock(() =>
   Promise.resolve({ host: 'github.com', owner: 'acme', name: 'myrepo' }),
 )
@@ -375,6 +402,326 @@ describe('callAutofixPr', () => {
   })
 })
 
+// Regression suite for the taskId-mismatch latent bug + completion hook wiring.
+// Before this fix, createAutofixTeammate generated a teammate UUID, that UUID
+// was used to acquire the singleton monitor lock, and registerRemoteAgentTask
+// generated a *different* framework taskId. When the framework eventually
+// called clearActiveMonitor(frameworkTaskId) on natural completion, the guard
+// failed (active.taskId !== frameworkTaskId) and the lock stayed acquired,
+// blocking any subsequent /autofix-pr invocations in the same process.
+describe('callAutofixPr · completion hook wiring (taskId mismatch regression)', () => {
+  test('updateActiveMonitor swaps lock taskId to framework-assigned id after register', async () => {
+    await callAutofixPr(onDone, makeContext(), '42')
+    const monitor = getActiveMonitor() as { taskId: string } | null
+    expect(monitor).not.toBeNull()
+    // registerMock returns 'framework-task-id'; before the fix this would be
+    // a teammate-generated random UUID instead.
+    expect(monitor?.taskId).toBe('framework-task-id')
+  })
+
+  test('framework hook → clearActiveMonitor releases lock on natural completion', async () => {
+    await callAutofixPr(onDone, makeContext(), '42')
+    expect(getActiveMonitor()).not.toBeNull()
+
+    // Find the hook the module registered at import time. We grab the last
+    // call so re-imports across tests don't break this — only the most recent
+    // registration is what the framework would invoke now.
+    const calls = registerCompletionHookMock.mock.calls
+    expect(calls.length).toBeGreaterThan(0)
+    const lastCall = calls[calls.length - 1]
+    expect(lastCall?.[0]).toBe('autofix-pr')
+    const hook = lastCall?.[1] as (id: string, metadata?: unknown) => void
+    expect(typeof hook).toBe('function')
+
+    // Simulate the framework invoking the hook with the framework taskId
+    // after a terminal transition. Before the fix this would no-op against
+    // a lock keyed by the teammate UUID.
+    hook('framework-task-id', { owner: 'acme', repo: 'myrepo', prNumber: 42 })
+    expect(getActiveMonitor()).toBeNull()
+  })
+
+  test('subsequent /autofix-pr succeeds after framework hook clears the lock', async () => {
+    await callAutofixPr(onDone, makeContext(), '42')
+    // Simulate natural completion via the registered hook
+    const calls = registerCompletionHookMock.mock.calls
+    const hook = calls[calls.length - 1]?.[1] as (
+      id: string,
+      metadata?: unknown,
+    ) => void
+    hook('framework-task-id', { owner: 'acme', repo: 'myrepo', prNumber: 42 })
+
+    onDone.mockClear()
+    await callAutofixPr(onDone, makeContext(), '99')
+    const firstArg = onDone.mock.calls[0]?.[0] as string
+    // Should be the success path, not "already monitoring"
+    expect(firstArg).not.toMatch(/already monitoring/i)
+    expect(firstArg).toMatch(/Autofix launched/)
+  })
+})
+
+// Phase 2: completionChecker wiring + initialHeadSha capture
+describe('callAutofixPr · Phase 2 completionChecker integration', () => {
+  test('completionChecker is registered at module load with autofix-pr type', () => {
+    // The registration happens during the beforeAll dynamic import; just
+    // verify the mock recorded a call. Filter by task type so any future
+    // additional registrations elsewhere don't break this assertion.
+    const calls = registerCompletionCheckerMock.mock.calls.filter(
+      c => c[0] === 'autofix-pr',
+    )
+    expect(calls.length).toBeGreaterThan(0)
+    const hook = calls[calls.length - 1]?.[1]
+    expect(typeof hook).toBe('function')
+  })
+
+  test('callAutofixPr captures initialHeadSha via fetchPrHeadSha', async () => {
+    fetchPrHeadShaMock.mockClear()
+    await callAutofixPr(onDone, makeContext(), '42')
+    expect(fetchPrHeadShaMock).toHaveBeenCalledWith('acme', 'myrepo', 42)
+  })
+
+  test('initialHeadSha is passed into remoteTaskMetadata on register', async () => {
+    fetchPrHeadShaMock.mockImplementationOnce(() =>
+      Promise.resolve('sha-from-launch'),
+    )
+    await callAutofixPr(onDone, makeContext(), '42')
+    expect(registerMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteTaskMetadata: expect.objectContaining({
+          owner: 'acme',
+          repo: 'myrepo',
+          prNumber: 42,
+          initialHeadSha: 'sha-from-launch',
+        }),
+      }),
+    )
+  })
+
+  test('fetchPrHeadSha failure → metadata initialHeadSha undefined, launch still succeeds', async () => {
+    fetchPrHeadShaMock.mockImplementationOnce(() =>
+      Promise.reject(new Error('gh not installed')),
+    )
+    await callAutofixPr(onDone, makeContext(), '42')
+    expect(registerMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteTaskMetadata: expect.objectContaining({
+          owner: 'acme',
+          repo: 'myrepo',
+          prNumber: 42,
+          initialHeadSha: undefined,
+        }),
+      }),
+    )
+    // Launch must NOT fail just because SHA capture failed
+    const firstArg = onDone.mock.calls[0]?.[0] as string
+    expect(firstArg).toMatch(/Autofix launched/)
+  })
+
+  test('fetchPrHeadSha returning null → metadata initialHeadSha undefined', async () => {
+    fetchPrHeadShaMock.mockImplementationOnce(() => Promise.resolve(null))
+    await callAutofixPr(onDone, makeContext(), '42')
+    expect(registerMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteTaskMetadata: expect.objectContaining({
+          initialHeadSha: undefined,
+        }),
+      }),
+    )
+  })
+})
+
+// Phase 2 (cont.): exercise the registered completionChecker arrow body
+// directly. The earlier suite verifies it was registered but never invokes
+// the arrow itself, leaving the throttle / metadata-guard / gh-CLI dispatch
+// branches uncovered.
+describe('callAutofixPr · Phase 2 completionChecker arrow body', () => {
+  // Pull the most recent registered checker — beforeAll registers once at
+  // module load; nothing else re-registers across this file's tests.
+  function getChecker(): (metadata?: unknown) => Promise<string | null> {
+    const calls = registerCompletionCheckerMock.mock.calls.filter(
+      c => c[0] === 'autofix-pr',
+    )
+    const fn = calls[calls.length - 1]?.[1]
+    if (typeof fn !== 'function') {
+      throw new Error('completionChecker not registered')
+    }
+    return fn
+  }
+
+  test('returns null when metadata is undefined (early guard)', async () => {
+    const checker = getChecker()
+    expect(await checker(undefined)).toBeNull()
+  })
+
+  test('returns null when checkPrAutofixOutcome reports not completed', async () => {
+    const { checkPrAutofixOutcome } = await import('../prFetch.js')
+    ;(checkPrAutofixOutcome as ReturnType<typeof mock>).mockImplementationOnce(
+      () => Promise.resolve({ completed: false }),
+    )
+    const checker = getChecker()
+    // Distinct PR number to dodge the in-process throttle map carried over
+    // from earlier tests.
+    const result = await checker({
+      owner: 'acme',
+      repo: 'myrepo',
+      prNumber: 1001,
+    })
+    expect(result).toBeNull()
+  })
+
+  test('returns the summary string when checkPrAutofixOutcome reports completed', async () => {
+    const { checkPrAutofixOutcome } = await import('../prFetch.js')
+    ;(checkPrAutofixOutcome as ReturnType<typeof mock>).mockImplementationOnce(
+      () =>
+        Promise.resolve({
+          completed: true,
+          summary: 'acme/myrepo#1002 merged. Autofix monitoring complete.',
+        }),
+    )
+    const checker = getChecker()
+    const result = await checker({
+      owner: 'acme',
+      repo: 'myrepo',
+      prNumber: 1002,
+    })
+    expect(result).toBe('acme/myrepo#1002 merged. Autofix monitoring complete.')
+  })
+
+  test('passes initialHeadSha through to checkPrAutofixOutcome', async () => {
+    const { checkPrAutofixOutcome } = await import('../prFetch.js')
+    const checkMock = checkPrAutofixOutcome as ReturnType<typeof mock>
+    checkMock.mockClear()
+    checkMock.mockImplementationOnce(() =>
+      Promise.resolve({ completed: false }),
+    )
+    const checker = getChecker()
+    await checker({
+      owner: 'acme',
+      repo: 'myrepo',
+      prNumber: 1003,
+      initialHeadSha: 'sha-baseline-xyz',
+    })
+    expect(checkMock).toHaveBeenCalledWith({
+      owner: 'acme',
+      repo: 'myrepo',
+      prNumber: 1003,
+      initialHeadSha: 'sha-baseline-xyz',
+    })
+  })
+
+  test('throttles back-to-back calls for the same PR within CHECK_INTERVAL_MS', async () => {
+    const { checkPrAutofixOutcome } = await import('../prFetch.js')
+    const checkMock = checkPrAutofixOutcome as ReturnType<typeof mock>
+    checkMock.mockClear()
+    checkMock.mockImplementation(() => Promise.resolve({ completed: false }))
+    const checker = getChecker()
+    const meta = { owner: 'acme', repo: 'myrepo', prNumber: 1004 }
+    await checker(meta)
+    // Second call within the 5s throttle window must short-circuit to null
+    // without invoking the gh CLI layer again.
+    const callCountAfterFirst = checkMock.mock.calls.length
+    const result = await checker(meta)
+    expect(result).toBeNull()
+    expect(checkMock.mock.calls.length).toBe(callCountAfterFirst)
+  })
+
+  test('completionHook with metadata clears the throttle entry (re-launch can re-check immediately)', async () => {
+    const { checkPrAutofixOutcome } = await import('../prFetch.js')
+    const checkMock = checkPrAutofixOutcome as ReturnType<typeof mock>
+    checkMock.mockClear()
+    checkMock.mockImplementation(() => Promise.resolve({ completed: false }))
+    const checker = getChecker()
+    const meta = { owner: 'acme', repo: 'myrepo', prNumber: 1005 }
+    await checker(meta) // populate throttle map
+
+    // Invoke the registered completion hook with the same metadata so the
+    // throttle entry is wiped, then verify the next checker call dispatches
+    // gh CLI again instead of short-circuiting.
+    const hookCalls = registerCompletionHookMock.mock.calls.filter(
+      c => c[0] === 'autofix-pr',
+    )
+    const hook = hookCalls[hookCalls.length - 1]?.[1] as (
+      id: string,
+      metadata?: unknown,
+    ) => void
+    hook('any-task-id', meta)
+
+    const callCountBefore = checkMock.mock.calls.length
+    await checker(meta)
+    expect(checkMock.mock.calls.length).toBe(callCountBefore + 1)
+  })
+
+  test('completionHook without metadata still clears the active monitor lock', async () => {
+    // Lock is set via callAutofixPr; hook then invoked with undefined metadata
+    // to exercise the `if (meta)` short-circuit branch (the lock-clear half
+    // still has to run regardless of metadata presence).
+    await callAutofixPr(onDone, makeContext(), '42')
+    expect(getActiveMonitor()).not.toBeNull()
+    const hookCalls = registerCompletionHookMock.mock.calls.filter(
+      c => c[0] === 'autofix-pr',
+    )
+    const hook = hookCalls[hookCalls.length - 1]?.[1] as (
+      id: string,
+      metadata?: unknown,
+    ) => void
+    hook('framework-task-id', undefined)
+    expect(getActiveMonitor()).toBeNull()
+  })
+})
+
+// Phase 3: content extractor wiring + initialMessage tag instruction
+describe('callAutofixPr · Phase 3 content extractor integration', () => {
+  test('registerContentExtractor is called at module load with autofix-pr type', () => {
+    const calls = registerContentExtractorMock.mock.calls.filter(
+      c => c[0] === 'autofix-pr',
+    )
+    expect(calls.length).toBeGreaterThan(0)
+    const extractor = calls[calls.length - 1]?.[1]
+    expect(typeof extractor).toBe('function')
+  })
+
+  test('initialMessage instructs the remote agent to emit an <autofix-result> tag', async () => {
+    await callAutofixPr(onDone, makeContext(), '42')
+    // teleportMock's typed signature has no args, so calls[0] is a
+    // zero-length tuple. We know teleportToRemote is invoked with one
+    // options object, so double-cast through unknown to read the args.
+    const calls = teleportMock.mock.calls as unknown as Array<
+      [{ initialMessage?: string }]
+    >
+    const teleportArgs = calls[0]?.[0]
+    expect(teleportArgs?.initialMessage).toContain('<autofix-result>')
+    expect(teleportArgs?.initialMessage).toContain('</autofix-result>')
+    expect(teleportArgs?.initialMessage).toContain('<ci-status>')
+    expect(teleportArgs?.initialMessage).toContain('<summary>')
+  })
+
+  test('registered extractor returns string for valid log and null for empty', () => {
+    const calls = registerContentExtractorMock.mock.calls.filter(
+      c => c[0] === 'autofix-pr',
+    )
+    const extractor = calls[calls.length - 1]?.[1] as
+      | ((log: unknown[]) => string | null)
+      | undefined
+    expect(extractor).toBeDefined()
+    // Empty log → null
+    expect(extractor?.([])).toBeNull()
+    // Log with assistant text containing tag → returns it
+    const logWithTag = [
+      {
+        type: 'assistant',
+        message: {
+          content: [
+            {
+              type: 'text',
+              text: 'done\n<autofix-result><summary>x</summary></autofix-result>',
+            },
+          ],
+        },
+      },
+    ]
+    expect(extractor?.(logWithTag)).toContain('<autofix-result>')
+  })
+})
+
 // Cover ../index.ts load() — placed in this test file so all the heavy mocks
 // (teleport / detectRepository / RemoteAgentTask / bootstrap-state / analytics /
 // skillDetect) are already registered when load() dynamically imports

src/commands/autofix-pr/__tests__/monitorState.test.ts

@@ -5,6 +5,7 @@ import {
   isMonitoring,
   setActiveMonitor,
   trySetActiveMonitor,
+  updateActiveMonitor,
 } from '../monitorState.js'
 
 function makeState(
@@ -76,4 +77,41 @@ describe('monitorState', () => {
     // First state remains
     expect(getActiveMonitor()?.prNumber).toBe(1)
   })
+
+  test('updateActiveMonitor returns false when no active monitor', () => {
+    expect(updateActiveMonitor({ taskId: 'task-x' })).toBe(false)
+    expect(getActiveMonitor()).toBeNull()
+  })
+
+  test('updateActiveMonitor merges partial fields into the active monitor', () => {
+    setActiveMonitor(makeState({ taskId: 'tentative-uuid' }))
+    expect(updateActiveMonitor({ taskId: 'framework-task-id' })).toBe(true)
+    const after = getActiveMonitor()
+    expect(after?.taskId).toBe('framework-task-id')
+    // Other fields untouched
+    expect(after?.owner).toBe('acme')
+    expect(after?.repo).toBe('myrepo')
+    expect(after?.prNumber).toBe(42)
+  })
+
+  test('updateActiveMonitor with new taskId makes clearActiveMonitor recognise framework taskId', () => {
+    // Reproduce the latent bug scenario: lock acquired with one taskId,
+    // framework assigns a different one. Before the fix, the framework's
+    // clearActiveMonitor(frameworkTaskId) would no-op because guard fails.
+    setActiveMonitor(makeState({ taskId: 'teammate-uuid' }))
+    // Framework cleanup using its own taskId — would fail guard before the fix
+    clearActiveMonitor('framework-uuid')
+    expect(getActiveMonitor()).not.toBeNull()
+    // After updateActiveMonitor swaps the taskId, framework cleanup works
+    updateActiveMonitor({ taskId: 'framework-uuid' })
+    clearActiveMonitor('framework-uuid')
+    expect(getActiveMonitor()).toBeNull()
+  })
+
+  test('updateActiveMonitor does not change abortController identity', () => {
+    const ac = new AbortController()
+    setActiveMonitor(makeState({ abortController: ac, taskId: 'tentative' }))
+    updateActiveMonitor({ taskId: 'updated' })
+    expect(getActiveMonitor()?.abortController).toBe(ac)
+  })
 })

src/commands/autofix-pr/__tests__/prOutcomeCheck.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type PrViewPayload,
+  summariseAutofixOutcome,
+} from '../prOutcomeCheck.js'
+
+function basePayload(overrides: Partial<PrViewPayload> = {}): PrViewPayload {
+  return {
+    headRefOid: 'sha-baseline',
+    state: 'OPEN',
+    statusCheckRollup: [],
+    ...overrides,
+  }
+}
+
+const identity = (overrides: Partial<{ initialHeadSha: string }> = {}) => ({
+  owner: 'acme',
+  repo: 'myrepo',
+  prNumber: 42,
+  initialHeadSha: 'sha-baseline',
+  ...overrides,
+})
+
+describe('summariseAutofixOutcome · terminal PR states', () => {
+  test('MERGED → completed regardless of head SHA / CI', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({ state: 'MERGED', headRefOid: 'sha-baseline' }),
+      identity(),
+    )
+    expect(result).toEqual({
+      completed: true,
+      summary: 'acme/myrepo#42 merged. Autofix monitoring complete.',
+    })
+  })
+
+  test('CLOSED → completed regardless of head SHA / CI', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({ state: 'CLOSED' }),
+      identity(),
+    )
+    expect(result).toEqual({
+      completed: true,
+      summary:
+        'acme/myrepo#42 closed without merge. Autofix monitoring complete.',
+    })
+  })
+})
+
+describe('summariseAutofixOutcome · OPEN PR without push', () => {
+  test('no initialHeadSha baseline → not completed (cannot detect push)', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({ state: 'OPEN' }),
+      identity({ initialHeadSha: undefined as unknown as string }),
+    )
+    expect(result).toEqual({ completed: false })
+  })
+
+  test('headRefOid unchanged → not completed (autofix has not pushed yet)', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({ state: 'OPEN', headRefOid: 'sha-baseline' }),
+      identity(),
+    )
+    expect(result).toEqual({ completed: false })
+  })
+})
+
+describe('summariseAutofixOutcome · OPEN PR with push, CI variations', () => {
+  test('push detected + no checks configured → completed (success)', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({
+        state: 'OPEN',
+        headRefOid: 'sha-new',
+        statusCheckRollup: [],
+      }),
+      identity(),
+    )
+    expect(result).toEqual({
+      completed: true,
+      summary: 'Autofix pushed commits to acme/myrepo#42, CI green.',
+    })
+  })
+
+  test('push detected + CI pending → not completed (wait for CI)', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({
+        state: 'OPEN',
+        headRefOid: 'sha-new',
+        statusCheckRollup: [
+          { status: 'IN_PROGRESS', conclusion: null, name: 'ci' },
+          { status: 'COMPLETED', conclusion: 'SUCCESS', name: 'lint' },
+        ],
+      }),
+      identity(),
+    )
+    expect(result).toEqual({ completed: false })
+  })
+
+  test('push detected + CI all green → completed (success summary)', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({
+        state: 'OPEN',
+        headRefOid: 'sha-new',
+        statusCheckRollup: [
+          { status: 'COMPLETED', conclusion: 'SUCCESS', name: 'ci' },
+          { status: 'COMPLETED', conclusion: 'SUCCESS', name: 'lint' },
+        ],
+      }),
+      identity(),
+    )
+    expect(result.completed).toBe(true)
+    if (result.completed) {
+      expect(result.summary).toContain('CI green')
+      expect(result.summary).toContain('acme/myrepo#42')
+    }
+  })
+
+  test('push detected + CI red → completed (failure summary surfaces the red)', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({
+        state: 'OPEN',
+        headRefOid: 'sha-new',
+        statusCheckRollup: [
+          { status: 'COMPLETED', conclusion: 'FAILURE', name: 'ci' },
+          { status: 'COMPLETED', conclusion: 'SUCCESS', name: 'lint' },
+        ],
+      }),
+      identity(),
+    )
+    expect(result.completed).toBe(true)
+    if (result.completed) {
+      expect(result.summary).toContain('CI is failing')
+      expect(result.summary).toContain('1/2 checks failing')
+    }
+  })
+
+  test('statusCheckRollup undefined → treated as no checks configured (success)', () => {
+    // Distinct from empty-array: GitHub omits the field entirely on PRs
+    // without any configured checks. The !rollup branch covers undefined.
+    const result = summariseAutofixOutcome(
+      basePayload({
+        state: 'OPEN',
+        headRefOid: 'sha-new',
+        statusCheckRollup: undefined,
+      }),
+      identity(),
+    )
+    expect(result.completed).toBe(true)
+    if (result.completed) {
+      expect(result.summary).toContain('CI green')
+    }
+  })
+
+  test('check with COMPLETED status but empty conclusion → counted as pending', () => {
+    // Edge case: GitHub sometimes reports a check as COMPLETED with a null/
+    // missing conclusion (in-flight result mid-write). The defensive branch
+    // treats empty conclusion after a passed status check as pending.
+    const result = summariseAutofixOutcome(
+      basePayload({
+        state: 'OPEN',
+        headRefOid: 'sha-new',
+        statusCheckRollup: [
+          { status: 'COMPLETED', conclusion: null, name: 'ci-in-flight' },
+          { status: 'COMPLETED', conclusion: 'SUCCESS', name: 'lint' },
+        ],
+      }),
+      identity(),
+    )
+    expect(result).toEqual({ completed: false })
+  })
+
+  test('neutral / skipped conclusions count as success (not failure)', () => {
+    const result = summariseAutofixOutcome(
+      basePayload({
+        state: 'OPEN',
+        headRefOid: 'sha-new',
+        statusCheckRollup: [
+          {
+            status: 'COMPLETED',
+            conclusion: 'NEUTRAL',
+            name: 'optional-check',
+          },
+          { status: 'COMPLETED', conclusion: 'SKIPPED', name: 'docs-check' },
+          { status: 'COMPLETED', conclusion: 'SUCCESS', name: 'ci' },
+        ],
+      }),
+      identity(),
+    )
+    expect(result.completed).toBe(true)
+    if (result.completed) {
+      expect(result.summary).toContain('CI green')
+    }
+  })
+})

src/commands/autofix-pr/extractAutofixResult.ts

@@ -0,0 +1,92 @@
+// Extract the <autofix-result> tag from a remote autofix-pr session log.
+//
+// The remote agent emits a structured XML block as its final message
+// (initialMessage in launchAutofixPr.ts instructs it to). The tag carries
+// PR-specific outcome data — commits pushed, files changed, CI status,
+// summary — that the framework's generic "task completed" notification
+// can't convey. We surface it to the local model by injecting the tag
+// verbatim into the message queue (analogous to <remote-review> handling).
+//
+// Resilient to two production realities:
+//   1. The tag may appear in either an assistant text block or a hook
+//      stdout (some autofix skills wrap the final report in a hook).
+//   2. The tag may not appear at all (older agents, truncated runs) —
+//      caller falls back to generic completion notification.
+
+import type {
+  SDKAssistantMessage,
+  SDKMessage,
+} from '../../entrypoints/agentSdkTypes.js'
+
+export const AUTOFIX_RESULT_TAG = 'autofix-result'
+
+const TAG_OPEN = `<${AUTOFIX_RESULT_TAG}>`
+const TAG_CLOSE = `</${AUTOFIX_RESULT_TAG}>`
+
+/**
+ * Walk the session log for an <autofix-result> tag. Returns the full tag
+ * (including delimiters) so the caller can inject it as-is into the
+ * notification; returns null if no tag is present.
+ *
+ * Search order:
+ *   1. Latest hook_progress / hook_response stdout (autofix skills that
+ *      use hooks to format the report write here first).
+ *   2. Latest assistant text block (agents that don't use hooks write the
+ *      tag inline in their final message).
+ *
+ * Latest-wins so re-tries within the same session don't surface stale
+ * earlier results.
+ */
+export function extractAutofixResultFromLog(log: SDKMessage[]): string | null {
+  // Walk backwards so we hit the most recent tag first.
+  for (let i = log.length - 1; i >= 0; i--) {
+    const msg = log[i]
+    if (!msg) continue
+
+    // Hook stdout (system messages of subtype hook_progress / hook_response).
+    if (
+      msg.type === 'system' &&
+      (msg.subtype === 'hook_progress' || msg.subtype === 'hook_response')
+    ) {
+      const stdout = (msg as { stdout?: unknown }).stdout
+      if (typeof stdout === 'string') {
+        const extracted = extractBetween(stdout, TAG_OPEN, TAG_CLOSE)
+        if (extracted) return extracted
+      }
+      continue
+    }
+
+    // Assistant text blocks.
+    if (msg.type === 'assistant') {
+      const content = (msg as SDKAssistantMessage).message?.content
+      if (!content || typeof content === 'string') continue
+      for (const block of content as Array<{ type: string; text?: string }>) {
+        if (block.type !== 'text' || typeof block.text !== 'string') continue
+        if (!block.text.includes(TAG_OPEN)) continue
+        const extracted = extractBetween(block.text, TAG_OPEN, TAG_CLOSE)
+        if (extracted) return extracted
+      }
+    }
+  }
+  return null
+}
+
+// Walks open tags from latest to earliest, returning the first complete
+// open/close pair. Guards against a truncated final tag shadowing an
+// earlier complete pair within the same text block (e.g., a retry wrote a
+// full result, then the model started a second tag that got cut off).
+function extractBetween(
+  text: string,
+  open: string,
+  close: string,
+): string | null {
+  let searchFrom = text.length
+  while (searchFrom >= 0) {
+    const start = text.lastIndexOf(open, searchFrom)
+    if (start === -1) return null
+    const end = text.indexOf(close, start + open.length)
+    if (end !== -1) return text.slice(start, end + close.length)
+    searchFrom = start - 1
+  }
+  return null
+}

src/commands/autofix-pr/launchAutofixPr.ts

@@ -13,7 +13,11 @@ import {
   checkRemoteAgentEligibility,
   formatPreconditionError,
   getRemoteTaskSessionUrl,
+  registerCompletionChecker,
+  registerCompletionHook,
+  registerContentExtractor,
   registerRemoteAgentTask,
+  type AutofixPrRemoteTaskMetadata,
   type BackgroundRemoteSessionPrecondition,
 } from '../../tasks/RemoteAgentTask/RemoteAgentTask.js'
 import type { LocalJSXCommandCall } from '../../types/command.js'
@@ -26,10 +30,66 @@ import {
   getActiveMonitor,
   isMonitoring,
   trySetActiveMonitor,
+  updateActiveMonitor,
 } from './monitorState.js'
+import { extractAutofixResultFromLog } from './extractAutofixResult.js'
 import { parseAutofixArgs } from './parseArgs.js'
+import { checkPrAutofixOutcome, fetchPrHeadSha } from './prFetch.js'
 import { detectAutofixSkills, formatSkillsHint } from './skillDetect.js'
 
+// Throttle map for the completionChecker: gh CLI is called at most once per
+// PR per CHECK_INTERVAL_MS, regardless of the framework's 1s poll cadence.
+// Key is `${owner}/${repo}#${prNumber}`. Cleared when the completion hook
+// fires so a re-launched monitor starts with a fresh budget.
+const lastCheckAt = new Map<string, number>()
+const CHECK_INTERVAL_MS = 5_000
+
+function throttleKey(meta: AutofixPrRemoteTaskMetadata): string {
+  return `${meta.owner}/${meta.repo}#${meta.prNumber}`
+}
+
+// Register the completionChecker once at module load. The framework calls it
+// on every poll tick for tasks with remoteTaskType==='autofix-pr'; throttle
+// inside so we don't fire gh CLI 60×/min. Returns the summary string on
+// completion (becomes the task-notification body) or null to keep polling.
+registerCompletionChecker('autofix-pr', async metadata => {
+  const meta = metadata as AutofixPrRemoteTaskMetadata | undefined
+  if (!meta) return null
+
+  const key = throttleKey(meta)
+  const now = Date.now()
+  if (now - (lastCheckAt.get(key) ?? 0) < CHECK_INTERVAL_MS) return null
+  lastCheckAt.set(key, now)
+
+  const result = await checkPrAutofixOutcome({
+    owner: meta.owner,
+    repo: meta.repo,
+    prNumber: meta.prNumber,
+    initialHeadSha: meta.initialHeadSha,
+  })
+  return result.completed ? result.summary : null
+})
+
+// Release the singleton monitor lock when the framework transitions the
+// autofix task to a terminal state. Without this, the lock — keyed by the
+// framework-assigned taskId (after callAutofixPr's updateActiveMonitor swap)
+// — would dangle past natural completion, blocking subsequent /autofix-pr
+// invocations until the process restarts. Registered at module load; the
+// framework's runCompletionHook invokes it once per terminal transition.
+// Also clear the per-PR throttle entry so a re-launch starts fresh.
+registerCompletionHook('autofix-pr', (taskId, metadata) => {
+  clearActiveMonitor(taskId)
+  const meta = metadata as AutofixPrRemoteTaskMetadata | undefined
+  if (meta) lastCheckAt.delete(throttleKey(meta))
+})
+
+// Phase 3 content return: extract the <autofix-result> tag from the session
+// log so the local model sees the agent's structured outcome (commits
+// pushed, files changed, CI status) inline in the completion task-
+// notification — instead of just a file-path pointer. The framework falls
+// back to the generic notification if extraction returns null.
+registerContentExtractor('autofix-pr', log => extractAutofixResultFromLog(log))
+
 function makeErrorText(message: string, code: string): string {
   logEvent('tengu_autofix_pr_result', {
     result:
@@ -198,7 +258,23 @@ export const callAutofixPr: LocalJSXCommandCall = async (
     // 4.5 compose message
     const target = `${owner}/${repo}#${prNumber}`
     const branchName = `refs/pull/${prNumber}/head`
-    const initialMessage = `Auto-fix failing CI checks on PR #${prNumber} in ${owner}/${repo}.${skillsHint}`
+    const initialMessage = `Auto-fix failing CI checks on PR #${prNumber} in ${owner}/${repo}.${skillsHint}
+
+When you finish (or hit a blocker you can't recover from), output the following XML tag as your final message so the local user gets a structured summary:
+
+<autofix-result>
+  <pr-number>${prNumber}</pr-number>
+  <commits-pushed>
+    <commit sha="...">commit message</commit>
+  </commits-pushed>
+  <files-changed>
+    <file path="...">N changes</file>
+  </files-changed>
+  <ci-status>green | red | pending | unknown</ci-status>
+  <summary>One-sentence summary of what was fixed or why it could not be fixed.</summary>
+</autofix-result>
+
+If no fix was needed, omit <commits-pushed> and <files-changed> and explain in <summary>. If you only attempted partial work, list the commits you did push and explain the remainder in <summary>.`
 
     // 4.6 in-process teammate
     const teammate = createAutofixTeammate(initialMessage, target)
@@ -274,18 +350,35 @@ export const callAutofixPr: LocalJSXCommandCall = async (
       return null
     }
 
+    // 4.8b capture PR head SHA before registering so the completionChecker
+    // can detect when the agent has pushed new commits. Best-effort — if gh
+    // is unavailable or the call fails, leave initialHeadSha undefined and
+    // the checker falls back to terminal-state-only completion (closed /
+    // merged). Don't block on this; teleport succeeded already.
+    const initialHeadSha =
+      (await fetchPrHeadSha(owner, repo, prNumber).catch(() => null)) ??
+      undefined
+
     // 4.9 register task. If this throws, release the lock so the user can
     // retry — the remote CCR session is already created so we surface a
     // dedicated error code.
+    //
+    // After registration succeeds, swap the lock's taskId from the tentative
+    // teammate UUID (used to acquire the lock atomically before teleport) to
+    // the framework-assigned taskId. Without this swap, the framework's own
+    // cleanup path (clearActiveMonitor(frameworkTaskId) on natural completion)
+    // would no-op against a lock keyed by teammate.taskId, leaving the
+    // singleton lock dangling and blocking future /autofix-pr invocations.
     try {
-      registerRemoteAgentTask({
+      const { taskId: frameworkTaskId } = registerRemoteAgentTask({
         remoteTaskType: 'autofix-pr',
         session,
         command: `/autofix-pr ${prNumber}`,
         context,
         isLongRunning: true,
-        remoteTaskMetadata: { owner, repo, prNumber },
+        remoteTaskMetadata: { owner, repo, prNumber, initialHeadSha },
       })
+      updateActiveMonitor({ taskId: frameworkTaskId })
     } catch (regErr: unknown) {
       clearActiveMonitor(teammate.taskId)
       const regMsg = regErr instanceof Error ? regErr.message : String(regErr)

src/commands/autofix-pr/monitorState.ts

@@ -46,6 +46,20 @@ export function clearActiveMonitor(taskId?: string): void {
   active = null
 }
 
+/**
+ * Atomically merges partial updates into the active monitor. Returns true if
+ * applied, false if no active monitor. Used when the caller needs to swap the
+ * lock's taskId after the framework assigns a different one than the
+ * tentative one used to acquire the lock — without this the framework's
+ * cleanup (clearActiveMonitor with the framework taskId) would no-op against
+ * a lock keyed by the caller's tentative id.
+ */
+export function updateActiveMonitor(partial: Partial<MonitorState>): boolean {
+  if (!active) return false
+  active = { ...active, ...partial }
+  return true
+}
+
 export function isMonitoring(
   owner: string,
   repo: string,

src/commands/autofix-pr/prFetch.ts

@@ -0,0 +1,155 @@
+// gh CLI integration for autofix-pr: fetches PR snapshots and feeds them
+// through the pure decision matrix in prOutcomeCheck.ts. Kept separate so
+// tests of the decision matrix never have to mock node:child_process — and
+// tests of callAutofixPr can mock this module without polluting the pure
+// decision matrix module (Bun mock.module is process-global).
+
+import { spawn } from 'node:child_process'
+import {
+  type AutofixOutcomeProbeResult,
+  type PrViewPayload,
+  summariseAutofixOutcome,
+} from './prOutcomeCheck.js'
+
+export interface AutofixOutcomeProbeInput {
+  owner: string
+  repo: string
+  prNumber: number
+  /**
+   * Head commit SHA captured at /autofix-pr launch. When this differs from
+   * the current head, autofix has pushed at least one commit.
+   */
+  initialHeadSha?: string
+  /**
+   * Timeout for the gh CLI invocation. Caller is the framework's per-tick
+   * poller, so failures must be bounded — a hung gh process would stall
+   * the entire poll loop.
+   */
+  timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000
+
+/**
+ * Fetch the PR's current head SHA, state, and CI rollup, and decide whether
+ * autofix has finished. Returns `{ completed: true, summary }` if so;
+ * otherwise `{ completed: false }`. Never throws.
+ */
+export async function checkPrAutofixOutcome(
+  input: AutofixOutcomeProbeInput,
+): Promise<AutofixOutcomeProbeResult> {
+  const { owner, repo, prNumber, initialHeadSha, timeoutMs } = input
+
+  let payload: PrViewPayload
+  try {
+    payload = await runGhPrView(
+      owner,
+      repo,
+      prNumber,
+      timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    )
+  } catch {
+    return { completed: false }
+  }
+
+  return summariseAutofixOutcome(payload, {
+    owner,
+    repo,
+    prNumber,
+    initialHeadSha,
+  })
+}
+
+/**
+ * Resolve the PR's current head commit SHA. Used at /autofix-pr launch to
+ * capture a baseline; later compared against the live SHA to detect pushes.
+ * Returns null on any failure (network, missing gh, permissions) — the
+ * caller treats null as "no baseline" and falls back to terminal-state-only
+ * completion detection.
+ */
+export async function fetchPrHeadSha(
+  owner: string,
+  repo: string,
+  prNumber: number,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<string | null> {
+  try {
+    const payload = await runGhPrView(owner, repo, prNumber, timeoutMs)
+    return payload.headRefOid || null
+  } catch {
+    return null
+  }
+}
+
+interface SpawnError extends Error {
+  code?: string
+}
+
+/**
+ * Spawn `gh pr view {n} --repo {owner}/{repo} --json ...` and parse the
+ * result. Rejects on non-zero exit, timeout, or JSON parse failure.
+ */
+function runGhPrView(
+  owner: string,
+  repo: string,
+  prNumber: number,
+  timeoutMs: number,
+): Promise<PrViewPayload> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(
+      'gh',
+      [
+        'pr',
+        'view',
+        String(prNumber),
+        '--repo',
+        `${owner}/${repo}`,
+        '--json',
+        'headRefOid,state,statusCheckRollup',
+      ],
+      { stdio: ['ignore', 'pipe', 'pipe'] },
+    )
+    const stdoutChunks: Buffer[] = []
+    const stderrChunks: Buffer[] = []
+    let settled = false
+
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      proc.kill('SIGKILL')
+      reject(new Error(`gh pr view timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    proc.stdout.on('data', chunk => stdoutChunks.push(chunk as Buffer))
+    proc.stderr.on('data', chunk => stderrChunks.push(chunk as Buffer))
+
+    proc.on('error', (err: SpawnError) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(err)
+    })
+
+    proc.on('close', code => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (code !== 0) {
+        const stderr = Buffer.concat(stderrChunks).toString('utf8').trim()
+        reject(
+          new Error(`gh pr view exited ${code}: ${stderr || '<no stderr>'}`),
+        )
+        return
+      }
+      const stdout = Buffer.concat(stdoutChunks).toString('utf8').trim()
+      try {
+        const parsed = JSON.parse(stdout) as PrViewPayload
+        resolve(parsed)
+      } catch (e) {
+        reject(
+          new Error(`gh pr view JSON parse failed: ${(e as Error).message}`),
+        )
+      }
+    })
+  })
+}

src/commands/autofix-pr/prOutcomeCheck.ts

@@ -0,0 +1,123 @@
+// Pure decision matrix for autofix-pr completion detection.
+//
+// Given a snapshot of the PR (state, head SHA, CI rollup) and a baseline
+// head SHA captured at /autofix-pr launch, decide whether autofix has
+// finished. No side effects — extracted from the gh CLI invocation in
+// prFetch.ts so unit tests can exercise every branch without spawning
+// subprocesses.
+
+export type AutofixOutcomeProbeResult =
+  | { completed: true; summary: string }
+  | { completed: false }
+
+export interface PrViewPayload {
+  headRefOid: string
+  state: 'OPEN' | 'CLOSED' | 'MERGED'
+  statusCheckRollup?: Array<{
+    conclusion?: string | null
+    status?: string | null
+    name?: string
+  }>
+}
+
+export interface AutofixOutcomeIdentity {
+  owner: string
+  repo: string
+  prNumber: number
+  /**
+   * Head commit SHA captured at /autofix-pr launch. When this differs from
+   * the current head, autofix has pushed at least one commit. Optional —
+   * absence means we can only finish on terminal PR states (merged/closed).
+   */
+  initialHeadSha?: string
+}
+
+/**
+ * Pure judgement of whether autofix has finished, given a PR snapshot and
+ * the baseline head SHA. Decision matrix:
+ *   - MERGED                         → done (merged)
+ *   - CLOSED (not merged)            → done (closed without fix)
+ *   - OPEN, no baseline              → keep polling
+ *   - OPEN, head unchanged           → keep polling (agent hasn't pushed)
+ *   - OPEN, head changed, CI pending → keep polling (wait for CI)
+ *   - OPEN, head changed, CI failure → done (surface red so user can retry)
+ *   - OPEN, head changed, CI success → done (clean fix)
+ */
+export function summariseAutofixOutcome(
+  payload: PrViewPayload,
+  identity: AutofixOutcomeIdentity,
+): AutofixOutcomeProbeResult {
+  const { owner, repo, prNumber, initialHeadSha } = identity
+
+  if (payload.state === 'MERGED') {
+    return {
+      completed: true,
+      summary: `${owner}/${repo}#${prNumber} merged. Autofix monitoring complete.`,
+    }
+  }
+  if (payload.state === 'CLOSED') {
+    return {
+      completed: true,
+      summary: `${owner}/${repo}#${prNumber} closed without merge. Autofix monitoring complete.`,
+    }
+  }
+
+  if (!initialHeadSha) return { completed: false }
+  if (payload.headRefOid === initialHeadSha) return { completed: false }
+
+  const ciState = summariseCiRollup(payload.statusCheckRollup)
+  if (ciState.state === 'pending') return { completed: false }
+  if (ciState.state === 'failure') {
+    return {
+      completed: true,
+      summary: `Autofix pushed commits to ${owner}/${repo}#${prNumber} but CI is failing (${ciState.detail}).`,
+    }
+  }
+  return {
+    completed: true,
+    summary: `Autofix pushed commits to ${owner}/${repo}#${prNumber}, CI green.`,
+  }
+}
+
+interface CiSummary {
+  state: 'success' | 'pending' | 'failure'
+  detail: string
+}
+
+function summariseCiRollup(
+  rollup: PrViewPayload['statusCheckRollup'],
+): CiSummary {
+  if (!rollup || rollup.length === 0) {
+    // No checks configured on this repo — treat as success so completion
+    // can fire on push alone. PRs without CI are perfectly valid.
+    return { state: 'success', detail: 'no checks configured' }
+  }
+  let pending = 0
+  let failed = 0
+  const total = rollup.length
+  for (const check of rollup) {
+    const status = (check.status ?? '').toUpperCase()
+    const conclusion = (check.conclusion ?? '').toUpperCase()
+    if (status && status !== 'COMPLETED') {
+      pending++
+      continue
+    }
+    if (
+      conclusion === 'SUCCESS' ||
+      conclusion === 'NEUTRAL' ||
+      conclusion === 'SKIPPED'
+    ) {
+      continue
+    }
+    if (conclusion === '') {
+      pending++
+      continue
+    }
+    failed++
+  }
+  if (pending > 0)
+    return { state: 'pending', detail: `${pending}/${total} checks pending` }
+  if (failed > 0)
+    return { state: 'failure', detail: `${failed}/${total} checks failing` }
+  return { state: 'success', detail: `${total}/${total} checks passing` }
+}

src/commands/effort/effort.tsx

@@ -155,7 +155,7 @@ export async function call(onDone: LocalJSXCommandOnDone, _context: unknown, arg
 
   if (COMMON_HELP_ARGS.includes(args)) {
     onDone(
-      'Usage: /effort [low|medium|high|xhigh|max|auto]\n\nEffort levels:\n- low: Quick, straightforward implementation\n- medium: Balanced approach with standard testing\n- high: Comprehensive implementation with extensive testing\n- xhigh: Extra high reasoning for supported models, including ChatGPT Codex models\n- max: Maximum capability with deepest reasoning where supported (Opus 4.6/4.7, DeepSeek V4 Pro); maps to xhigh for ChatGPT Codex models\n- auto: Use the default effort level for your model',
+      'Usage: /effort [low|medium|high|xhigh|max|auto]\n\nEffort levels:\n- low: Quick, straightforward implementation\n- medium: Balanced approach with standard testing\n- high: Comprehensive implementation with extensive testing\n- xhigh: Extended reasoning beyond high, short of max; including ChatGPT Codex models\n- max: Maximum capability with deepest reasoning; maps to xhigh for ChatGPT Codex models\n- auto: Use the default effort level for your model',
     );
     return;
   }

src/commands/issue/__tests__/issue-gh.test.ts

@@ -1,571 +0,0 @@
-/**
- * Coverage tests for issue/index.ts gh-CLI paths.
- *
- * issue/index.ts uses `import * as childProcess from 'node:child_process'`
- * with lazy promisify, so mock.module('node:child_process') is effective.
- */
-import {
-  afterAll,
-  afterEach,
-  beforeAll,
-  beforeEach,
-  describe,
-  expect,
-  mock,
-  test,
-} from 'bun:test'
-import { promisify } from 'node:util'
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-// ── Mock control state ──
-let _execFileSyncImpl: (cmd: string, args: string[], opts?: unknown) => Buffer =
-  () => Buffer.from('')
-
-let _execFileImpl: (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-  cb: (err: Error | null, stdout: string, stderr: string) => void,
-) => void = (_cmd, _args, _opts, cb) => cb(null, '', '')
-
-const execFileSyncMockCore = (
-  cmd: string,
-  args: string[],
-  opts?: unknown,
-): Buffer => _execFileSyncImpl(cmd, args, opts)
-
-const execFileMockCore = (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-  cb: (err: Error | null, stdout: string, stderr: string) => void,
-) => _execFileImpl(cmd, args, opts, cb)
-
-;(execFileMockCore as unknown as Record<symbol, unknown>)[
-  promisify.custom as symbol
-] = (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-): Promise<{ stdout: string; stderr: string }> =>
-  new Promise((resolve, reject) =>
-    _execFileImpl(cmd, args, opts, (err, stdout, stderr) => {
-      if (err) reject(err)
-      else resolve({ stdout, stderr })
-    }),
-  )
-
-// Spread real child_process + flag-gated stub (see share-gh.test.ts for the
-// promisify.custom rationale).
-let useIssueGhCpStubs = false
-const wrappedIssueGhExecFile = ((...args: unknown[]) =>
-  useIssueGhCpStubs
-    ? (execFileMockCore as (...a: unknown[]) => unknown)(...args)
-    : // eslint-disable-next-line @typescript-eslint/no-require-imports
-      (require('node:child_process').execFile as (...a: unknown[]) => unknown)(
-        ...args,
-      )) as unknown as Record<symbol, unknown> & ((...a: unknown[]) => unknown)
-;(wrappedIssueGhExecFile as Record<symbol, unknown>)[
-  promisify.custom as symbol
-] = (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-): Promise<{ stdout: string; stderr: string }> => {
-  if (useIssueGhCpStubs) {
-    return new Promise((resolve, reject) =>
-      _execFileImpl(cmd, args, opts, (err, stdout, stderr) =>
-        err ? reject(err) : resolve({ stdout, stderr }),
-      ),
-    )
-  }
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const real = require('node:child_process') as Record<string, unknown>
-  return promisify(real.execFile as never)(cmd, args, opts) as Promise<{
-    stdout: string
-    stderr: string
-  }>
-}
-mock.module('node:child_process', () => {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const real = require('node:child_process') as Record<string, unknown>
-  return {
-    ...real,
-    default: real,
-    execFile: wrappedIssueGhExecFile as typeof real.execFile,
-    execFileSync: ((...args: unknown[]) =>
-      useIssueGhCpStubs
-        ? (execFileSyncMockCore as (...a: unknown[]) => unknown)(...args)
-        : (real.execFileSync as (...a: unknown[]) => unknown)(
-            ...args,
-          )) as typeof real.execFileSync,
-  }
-})
-
-mock.module('bun:bundle', () => ({
-  feature: (_name: string) => true,
-}))
-
-mock.module('src/services/analytics/index.js', () => ({
-  logEvent: () => {},
-  stripProtoFields: (v: unknown) => v,
-}))
-
-// ── State ──
-let tmpDir: string
-let claudeDir: string
-
-beforeEach(() => {
-  tmpDir = mkdtempSync(join(tmpdir(), 'issue-gh-test-'))
-  claudeDir = join(tmpDir, '.claude')
-  mkdirSync(claudeDir, { recursive: true })
-  process.env.CLAUDE_CONFIG_DIR = claudeDir
-  // Default: git remote fails (no GitHub remote), gh not available
-  _execFileSyncImpl = (_cmd, _args, _opts) => {
-    throw new Error('ENOENT: command not found')
-  }
-  _execFileImpl = (_cmd, _args, _opts, cb) =>
-    cb(new Error('ENOENT: command not found'), '', '')
-})
-
-afterEach(() => {
-  rmSync(tmpDir, { recursive: true, force: true })
-  delete process.env.CLAUDE_CONFIG_DIR
-})
-
-// ── Helpers ──
-type CallFn = (args: string) => Promise<{ type: string; value: string }>
-
-async function getCallFn(): Promise<CallFn> {
-  const mod = await import('../index.js')
-  const loaded = await (
-    mod.default as unknown as { load: () => Promise<{ call: CallFn }> }
-  ).load()
-  return loaded.call.bind(loaded) as CallFn
-}
-
-async function writeSessionLog(entries?: string[]): Promise<void> {
-  const { sanitizePath } = await import('../../../utils/path.js')
-  const { getSessionId, getOriginalCwd } = await import(
-    '../../../bootstrap/state.js'
-  )
-  const sessionId = getSessionId()
-  const cwd = getOriginalCwd()
-  const encoded = sanitizePath(cwd)
-  const dir = join(claudeDir, 'projects', encoded)
-  mkdirSync(dir, { recursive: true })
-  const content = entries ?? [
-    JSON.stringify({ role: 'user', content: 'Fix the login bug' }),
-    JSON.stringify({
-      role: 'assistant',
-      content: [{ type: 'text', text: 'I will investigate' }],
-    }),
-  ]
-  writeFileSync(join(dir, `${sessionId}.jsonl`), content.join('\n') + '\n')
-}
-
-// Create a .github/ISSUE_TEMPLATE dir in tmpDir
-function createIssueTemplate(
-  content = '## Bug Report\n\nDescribe the bug.',
-): string {
-  const templateDir = join(tmpDir, '.github', 'ISSUE_TEMPLATE')
-  mkdirSync(templateDir, { recursive: true })
-  writeFileSync(join(templateDir, 'bug_report.md'), content)
-  return templateDir
-}
-
-// ── Sequence helpers ──
-type SeqBehavior =
-  | { type: 'sync-ok'; stdout: string }
-  | { type: 'sync-fail'; msg: string }
-  | { type: 'async-ok'; stdout: string }
-  | { type: 'async-fail'; msg: string }
-
-/**
- * Sets sync/async behavior based on command name.
- * syncBehavior controls execFileSync (git, gh --version sync-check).
- * asyncBehaviors controls sequential async calls.
- */
-function setupMocks(opts: {
-  gitRemoteUrl?: string | null // null = git fails, string = succeeds with that URL
-  ghCliAvailable?: boolean // whether gh --version sync call succeeds
-  asyncSequence?: Array<
-    { ok: true; stdout: string } | { ok: false; msg: string }
-  >
-}): void {
-  const { gitRemoteUrl, ghCliAvailable = false, asyncSequence = [] } = opts
-
-  _execFileSyncImpl = (cmd, _args, _opts) => {
-    if (cmd === 'git') {
-      if (gitRemoteUrl !== null && gitRemoteUrl !== undefined) {
-        return Buffer.from(gitRemoteUrl + '\n')
-      }
-      throw new Error('ENOENT: git not found or no remote')
-    }
-    if (cmd === 'gh') {
-      if (ghCliAvailable) {
-        return Buffer.from('gh version 2.0.0')
-      }
-      throw new Error('ENOENT: gh not found')
-    }
-    throw new Error(`Unexpected sync command: ${cmd}`)
-  }
-
-  let asyncCallCount = 0
-  _execFileImpl = (_cmd, _args, _opts, cb) => {
-    const b = asyncSequence[asyncCallCount] ?? {
-      ok: false,
-      msg: 'unexpected async call',
-    }
-    asyncCallCount++
-    if (b.ok) cb(null, b.stdout, '')
-    else cb(new Error(b.msg), '', b.msg)
-  }
-}
-
-// Activate child_process stubs only for this suite.
-beforeAll(() => {
-  useIssueGhCpStubs = true
-})
-afterAll(() => {
-  useIssueGhCpStubs = false
-})
-
-describe('issue command — tryDetectGitRemoteUrl catch path', () => {
-  test('git fails → tryDetectGitRemoteUrl returns null → no remote detected', async () => {
-    setupMocks({ gitRemoteUrl: null, ghCliAvailable: false })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    // No remote + no gh → fallback URL path
-    expect(result.value).toContain('GitHub')
-  })
-})
-
-describe('issue command — ghCliAvailable paths', () => {
-  test('gh not available → falls back to browser URL (with GitHub remote)', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: false,
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('github.com/owner/repo')
-    expect(result.value).toContain('Install')
-  })
-
-  test('gh not available + no remote → shows no GitHub remote message', async () => {
-    setupMocks({ gitRemoteUrl: null, ghCliAvailable: false })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('GitHub')
-  })
-
-  test('gh available + no remote → falls back to browser (no URL)', async () => {
-    setupMocks({
-      gitRemoteUrl: null,
-      ghCliAvailable: true,
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('GitHub')
-  })
-})
-
-describe('issue command — parseOwnerRepo null path', () => {
-  test('non-GitHub remote → parseOwnerRepo returns null → no gh URL', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://gitlab.com/owner/repo.git',
-      ghCliAvailable: true,
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-  })
-})
-
-describe('issue command — repoHasIssuesEnabled paths', () => {
-  test('gh available + GitHub remote → issues enabled (true) → creates issue', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' }, // gh api repos → has_issues = true
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/42' }, // gh issue create
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-    expect(result.value).toContain('Fix login bug')
-    expect(result.value).toContain('https://github.com/owner/repo/issues/42')
-  })
-
-  test('gh available + GitHub remote → issues disabled (false) → discussions fallback', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'false\n' }, // gh api repos → has_issues = false
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issues are disabled')
-    expect(result.value).toContain('discussions')
-  })
-
-  test('gh available + GitHub remote → repoHasIssuesEnabled returns null (unexpected output)', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'null\n' }, // unexpected .has_issues value → null
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/99' }, // issue create
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    // null → proceeds to create issue
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('gh available + GitHub remote → repoHasIssuesEnabled throws → returns null → creates issue', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: false, msg: 'network error' }, // gh api fails → catch → null
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/101' }, // issue create
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('gh available + GitHub remote + issue create fails → error message', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' }, // has_issues = true
-        { ok: false, msg: 'gh auth error' }, // issue create fails
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Failed to create issue')
-    expect(result.value).toContain('gh auth error')
-  })
-
-  test('gh available + GitHub remote + labels and assignees → issue created with labels', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/50' },
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('--label bug --assignee alice Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-    expect(result.value).toContain('Labels: bug')
-    expect(result.value).toContain('Assignees: alice')
-  })
-})
-
-describe('issue command — detectIssueTemplate paths', () => {
-  test('no .github/ISSUE_TEMPLATE → no template used', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/1' },
-      ],
-    })
-    process.env.INIT_CWD = tmpDir
-    // Ensure no ISSUE_TEMPLATE exists
-    const call = await getCallFn()
-    const result = await call('Test no template')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('.github/ISSUE_TEMPLATE with md file → template included in body', async () => {
-    createIssueTemplate('---\nname: Bug Report\n---\n## Describe the bug')
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/2' },
-      ],
-    })
-    // Override getOriginalCwd to return tmpDir by setting env
-    // detectIssueTemplate uses `cwd = getOriginalCwd()` from state
-    // which returns the real process cwd. We create template relative to real cwd
-    // This test just verifies the path doesn't crash.
-    const call = await getCallFn()
-    const result = await call('Test with template')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-  })
-
-  test('.github/ISSUE_TEMPLATE with only yml files → no md template', async () => {
-    const templateDir = join(tmpDir, '.github', 'ISSUE_TEMPLATE')
-    mkdirSync(templateDir, { recursive: true })
-    writeFileSync(join(templateDir, 'bug.yml'), 'name: Bug\ndescription: A bug')
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/3' },
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Test yml template')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-  })
-})
-
-describe('issue command — getTranscriptSummary paths', () => {
-  test('session log exists + projectDir=null → reads from standard path', async () => {
-    await writeSessionLog()
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/4' },
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('session log with tool_result errors → errors included in summary', async () => {
-    await writeSessionLog([
-      JSON.stringify({
-        role: 'user',
-        content: [
-          {
-            type: 'tool_result',
-            tool_use_id: 'tu1',
-            is_error: true,
-            content: 'Command failed with exit code 1',
-          },
-        ],
-      }),
-      JSON.stringify({ role: 'user', content: 'help me' }),
-      JSON.stringify({ role: 'assistant', content: 'let me look' }),
-    ])
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/5' },
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix crash')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('session log with array content user message', async () => {
-    await writeSessionLog([
-      JSON.stringify({
-        role: 'user',
-        content: [{ type: 'text', text: 'What is the issue?' }],
-      }),
-    ])
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/6' },
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Test array content')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('no session log → getTranscriptSummary returns no session log found', async () => {
-    // No log written → summary says "(no session log found)"
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/repo/issues/7' },
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix issue no log')
-    expect(result.type).toBe('text')
-    // Either creates issue successfully or fails, but passes the code paths
-    expect(typeof result.value).toBe('string')
-  })
-})
-
-describe('issue command — SSH GitHub remote', () => {
-  test('SSH remote parsed correctly → issue created', async () => {
-    setupMocks({
-      gitRemoteUrl: 'git@github.com:owner/myrepo.git',
-      ghCliAvailable: true,
-      asyncSequence: [
-        { ok: true, stdout: 'true\n' },
-        { ok: true, stdout: 'https://github.com/owner/myrepo/issues/8' },
-      ],
-    })
-    const call = await getCallFn()
-    const result = await call('Fix SSH issue')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-})
-
-describe('issue command — no title with remote present', () => {
-  test('no title + GitHub remote + gh available → usage with repo info and gh message', async () => {
-    setupMocks({
-      gitRemoteUrl: 'https://github.com/owner/repo.git',
-      ghCliAvailable: true,
-    })
-    const call = await getCallFn()
-    const result = await call('')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Usage')
-    expect(result.value).toContain('owner/repo')
-  })
-
-  test('no title + no remote + gh not available → usage with no repo info', async () => {
-    setupMocks({ gitRemoteUrl: null, ghCliAvailable: false })
-    const call = await getCallFn()
-    const result = await call('')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Usage')
-  })
-})

src/commands/issue/__tests__/issue-template.test.ts

@@ -1,261 +0,0 @@
-/**
- * Coverage tests for detectIssueTemplate paths.
- *
- * detectIssueTemplate uses getOriginalCwd() to find .github/ISSUE_TEMPLATE.
- * These tests create the template directory in the REAL project CWD and clean
- * up after each test.
- *
- * IMPORTANT: No state mock is used — this avoids global mock contamination.
- */
-import {
-  afterAll,
-  afterEach,
-  beforeAll,
-  beforeEach,
-  describe,
-  expect,
-  mock,
-  test,
-} from 'bun:test'
-import { promisify } from 'node:util'
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-
-// ── child_process mock ──
-let _execFileSyncImplT: (
-  cmd: string,
-  args: string[],
-  opts?: unknown,
-) => Buffer = () => Buffer.from('')
-let _execFileImplT: (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-  cb: (err: Error | null, stdout: string, stderr: string) => void,
-) => void = (_cmd, _args, _opts, cb) => cb(null, '', '')
-
-const execFileSyncMockT = (
-  cmd: string,
-  args: string[],
-  opts?: unknown,
-): Buffer => _execFileSyncImplT(cmd, args, opts)
-const execFileMockT = (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-  cb: (err: Error | null, stdout: string, stderr: string) => void,
-) => _execFileImplT(cmd, args, opts, cb)
-
-;(execFileMockT as unknown as Record<symbol, unknown>)[
-  promisify.custom as symbol
-] = (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-): Promise<{ stdout: string; stderr: string }> =>
-  new Promise((resolve, reject) =>
-    _execFileImplT(cmd, args, opts, (err, stdout, stderr) => {
-      if (err) reject(err)
-      else resolve({ stdout, stderr })
-    }),
-  )
-
-// Spread real child_process + flag-gated stub (see share-gh.test.ts for the
-// promisify.custom rationale).
-let useIssueTemplateCpStubs = false
-const wrappedIssueTemplateExecFile = ((...args: unknown[]) =>
-  useIssueTemplateCpStubs
-    ? (execFileMockT as (...a: unknown[]) => unknown)(...args)
-    : // eslint-disable-next-line @typescript-eslint/no-require-imports
-      (require('node:child_process').execFile as (...a: unknown[]) => unknown)(
-        ...args,
-      )) as unknown as Record<symbol, unknown> & ((...a: unknown[]) => unknown)
-;(wrappedIssueTemplateExecFile as Record<symbol, unknown>)[
-  promisify.custom as symbol
-] = (
-  cmd: string,
-  args: string[],
-  opts: unknown,
-): Promise<{ stdout: string; stderr: string }> => {
-  if (useIssueTemplateCpStubs) {
-    return new Promise((resolve, reject) =>
-      _execFileImplT(cmd, args, opts, (err, stdout, stderr) =>
-        err ? reject(err) : resolve({ stdout, stderr }),
-      ),
-    )
-  }
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const real = require('node:child_process') as Record<string, unknown>
-  return promisify(real.execFile as never)(cmd, args, opts) as Promise<{
-    stdout: string
-    stderr: string
-  }>
-}
-mock.module('node:child_process', () => {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const real = require('node:child_process') as Record<string, unknown>
-  return {
-    ...real,
-    default: real,
-    execFile: wrappedIssueTemplateExecFile as typeof real.execFile,
-    execFileSync: ((...args: unknown[]) =>
-      useIssueTemplateCpStubs
-        ? (execFileSyncMockT as (...a: unknown[]) => unknown)(...args)
-        : (real.execFileSync as (...a: unknown[]) => unknown)(
-            ...args,
-          )) as typeof real.execFileSync,
-  }
-})
-
-mock.module('bun:bundle', () => ({
-  feature: (_name: string) => true,
-}))
-
-mock.module('src/services/analytics/index.js', () => ({
-  logEvent: () => {},
-  stripProtoFields: (v: unknown) => v,
-}))
-
-// Re-mock bootstrap/state.js so getOriginalCwd points at the real process
-// cwd regardless of any prior test file's static state mock (e.g.
-// launchAutofixPr.test.ts pinning '/mock/cwd'). Without this override, in
-// the full suite detectIssueTemplate would see '/mock/cwd' and skip the
-// template loading body (lines 114-129).
-import { stateMock as _baseStateMockT } from '../../../../tests/mocks/state'
-let _dynamicCwdT: string = process.cwd()
-mock.module('src/bootstrap/state.js', () => ({
-  ..._baseStateMockT(),
-  getSessionId: () => 'issue-tpl-session-id',
-  getSessionProjectDir: () => null,
-  getOriginalCwd: () => _dynamicCwdT,
-  setOriginalCwd: (c: string) => {
-    _dynamicCwdT = c
-  },
-}))
-
-// ── State ──
-let tmpDir: string
-let claudeDir: string
-
-// The real CWD where the issue command will look for .github/ISSUE_TEMPLATE
-// We determine this at import time (stable throughout test run)
-const realCwd = process.cwd()
-// We track whether we created the template dir so we can clean it up
-let createdTemplatePath: string | null = null
-
-beforeEach(() => {
-  tmpDir = mkdtempSync(join(tmpdir(), 'issue-tpl-test-'))
-  claudeDir = join(tmpDir, '.claude')
-  mkdirSync(claudeDir, { recursive: true })
-  process.env.CLAUDE_CONFIG_DIR = claudeDir
-  createdTemplatePath = null
-
-  // Default: git → GitHub remote, gh → available, async → issues true + create OK
-  let n = 0
-  _execFileSyncImplT = (cmd, _args, _opts) => {
-    if (cmd === 'git') return Buffer.from('https://github.com/owner/repo.git\n')
-    if (cmd === 'gh') return Buffer.from('gh version 2.0.0')
-    return Buffer.from('')
-  }
-  _execFileImplT = (_cmd, _args, _opts, cb) => {
-    n++
-    if (n === 1) cb(null, 'true\n', '')
-    else cb(null, 'https://github.com/owner/repo/issues/20', '')
-  }
-})
-
-afterEach(() => {
-  rmSync(tmpDir, { recursive: true, force: true })
-  delete process.env.CLAUDE_CONFIG_DIR
-  // Clean up any template dir we created in the real CWD
-  if (createdTemplatePath && existsSync(createdTemplatePath)) {
-    rmSync(createdTemplatePath, { recursive: true, force: true })
-  }
-  createdTemplatePath = null
-})
-
-// ── Helpers ──
-type CallFn = (args: string) => Promise<{ type: string; value: string }>
-
-async function getCallFn(): Promise<CallFn> {
-  const mod = await import('../index.js')
-  const loaded = await (
-    mod.default as unknown as { load: () => Promise<{ call: CallFn }> }
-  ).load()
-  return loaded.call.bind(loaded) as CallFn
-}
-
-/**
- * Creates .github/ISSUE_TEMPLATE in the REAL CWD.
- * Registers for cleanup in afterEach.
- */
-function createTemplateInCwd(files: Record<string, string>): string {
-  const templateDir = join(realCwd, '.github', 'ISSUE_TEMPLATE')
-  mkdirSync(templateDir, { recursive: true })
-  for (const [name, content] of Object.entries(files)) {
-    writeFileSync(join(templateDir, name), content)
-  }
-  // Track the ISSUE_TEMPLATE dir for cleanup — never delete the whole .github/
-  // as it may contain workflows, settings, or other project config.
-  createdTemplatePath = templateDir
-  return templateDir
-}
-
-// Activate child_process stubs only for this suite.
-beforeAll(() => {
-  useIssueTemplateCpStubs = true
-})
-afterAll(() => {
-  useIssueTemplateCpStubs = false
-})
-
-describe('issue command — detectIssueTemplate template paths', () => {
-  test('md template with front-matter → front-matter stripped', async () => {
-    createTemplateInCwd({
-      'bug.md':
-        '---\nname: Bug Report\nabout: A bug\n---\n## Describe the bug\n\nDetails.',
-    })
-    const call = await getCallFn()
-    const result = await call('Fix bug with template')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('md template without front-matter → content returned as-is', async () => {
-    createTemplateInCwd({
-      'feature.md': '## Feature Request\n\nDescribe the feature.',
-    })
-    const call = await getCallFn()
-    const result = await call('Add feature')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('yml file only → mdFile not found → no template (null)', async () => {
-    createTemplateInCwd({
-      'bug.yml': 'name: Bug\ndescription: Describe the bug.',
-    })
-    const call = await getCallFn()
-    const result = await call('Fix yml-only template issue')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-
-  test('md template stripped to empty → null (stripped || null)', async () => {
-    // Front-matter only, empty body after stripping
-    createTemplateInCwd({
-      'empty.md': '---\nname: Empty\nabout: empty\n---',
-    })
-    const call = await getCallFn()
-    const result = await call('Empty template test')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Issue created')
-  })
-})

src/commands/issue/__tests__/issue.test.ts

@@ -1,611 +0,0 @@
-/**
- * Tests for issue/index.ts
- *
- * NOTE: issue/index.ts calls execFileSync at module-function level (not top-level).
- * The child_process functions are imported by reference and cannot be reliably
- * mocked after module load with Bun's mock.module. Tests here cover what's
- * testable without child_process control: parseIssueArgs, metadata, and
- * environment-agnostic paths.
- */
-import {
-  afterAll,
-  afterEach,
-  beforeAll,
-  beforeEach,
-  describe,
-  expect,
-  mock,
-  test,
-} from 'bun:test'
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { randomUUID } from 'node:crypto'
-
-mock.module('bun:bundle', () => ({
-  feature: (_name: string) => true,
-}))
-
-mock.module('src/services/analytics/index.js', () => ({
-  logEvent: () => {},
-  logEventAsync: () => Promise.resolve(),
-  stripProtoFields: (v: unknown) => v,
-  _resetForTesting: () => {},
-  attachAnalyticsSink: () => {},
-}))
-
-// Re-mock bootstrap/state.js with a dynamic getOriginalCwd / setOriginalCwd
-// pair so this suite can drive cwd values regardless of any earlier test
-// file's static mock (e.g. launchAutofixPr.test.ts which sets a fixed
-// '/mock/cwd'). We start from the shared stateMock helper, then override
-// the four exports issue/index.ts cares about with closure-driven impls.
-//
-// Bun's mock.module is global / last-write-wins. After this suite finishes
-// we set `useIssueDynamicState=false` so launchAutofixPr's tests (which run
-// in the same process) see the values their suite originally expected.
-import { stateMock } from '../../../../tests/mocks/state'
-let _dynamicCwd = process.cwd()
-let _dynamicSessionId = `issue-test-${randomUUID()}`
-// Default OFF — autofix-pr/__tests__/launchAutofixPr.test.ts runs FIRST in
-// the combined suite (alphabetical: 'autofix-pr' < 'issue') and expects
-// '/mock/cwd'. Issue's beforeAll switches this on, afterAll switches off.
-let useIssueDynamicState = false
-// Default OFF — the long-body draft-save test below flips this on for its
-// body (so execFile/execFileSync return ENOENT + a fake GitHub remote URL)
-// then flips off in finally. Without the flag the child_process stub leaked
-// process-globally into every later test file via Bun's mock.module cache.
-let useIssueLongBodyCpStubs = false
-mock.module('src/bootstrap/state.js', () => ({
-  ...stateMock(),
-  getSessionId: () =>
-    useIssueDynamicState ? _dynamicSessionId : 'parent-session-id',
-  getParentSessionId: () => undefined,
-  getCwdState: () => (useIssueDynamicState ? _dynamicCwd : '/mock/cwd'),
-  getSessionProjectDir: () => null,
-  getOriginalCwd: () => (useIssueDynamicState ? _dynamicCwd : '/mock/cwd'),
-  getProjectRoot: () => (useIssueDynamicState ? _dynamicCwd : '/mock/project'),
-  setCwdState: (c: string) => {
-    if (useIssueDynamicState) _dynamicCwd = c
-  },
-  setOriginalCwd: (c: string) => {
-    if (useIssueDynamicState) _dynamicCwd = c
-  },
-  setLastAPIRequestMessages: () => {},
-  getIsNonInteractiveSession: () => false,
-  addSlowOperation: () => {},
-}))
-
-// ── State ──
-let tmpDir: string
-let claudeDir: string
-// Snapshot HOME so per-test mutations (lines below set process.env.HOME =
-// tmpDir for child-process branches) can be restored. Otherwise the leaked
-// /tmp/issue-test-XXX HOME pollutes downstream tests like
-// src/services/langfuse/__tests__/langfuse.test.ts whose sanitize logic
-// substitutes the current process.env.HOME.
-const _originalHomeForIssueSuite = process.env.HOME
-
-// Mock envUtils to read CLAUDE_CONFIG_DIR from process.env dynamically so
-// other test files (cacheStats, SessionMemory/prompts) that mock with static
-// paths don't pollute this test in the full suite. Reading process.env at
-// call time lets each test drive its own dir.
-mock.module('src/utils/envUtils.js', () => ({
-  getClaudeConfigHomeDir: () =>
-    process.env.CLAUDE_CONFIG_DIR ?? `${tmpdir()}/dummy-claude`,
-  isEnvTruthy: (v: unknown) => Boolean(v),
-  getTeamsDir: () =>
-    join(process.env.CLAUDE_CONFIG_DIR ?? `${tmpdir()}/dummy-claude`, 'teams'),
-  hasNodeOption: () => false,
-  isEnvDefinedFalsy: () => false,
-  isBareMode: () => false,
-  parseEnvVars: (s: string) => s,
-  getAWSRegion: () => 'us-east-1',
-  getDefaultVertexRegion: () => 'us-central1',
-  shouldMaintainProjectWorkingDir: () => false,
-}))
-
-// Activate dynamic state mode for this suite only.
-beforeAll(() => {
-  useIssueDynamicState = true
-})
-
-beforeEach(() => {
-  tmpDir = mkdtempSync(join(tmpdir(), 'issue-test-'))
-  claudeDir = join(tmpDir, '.claude')
-  mkdirSync(claudeDir, { recursive: true })
-  process.env.CLAUDE_CONFIG_DIR = claudeDir
-  // Reset dynamic cwd to a per-test deterministic default (the tmpDir).
-  // Tests that need a different cwd call the mocked setOriginalCwd.
-  _dynamicCwd = tmpDir
-  _dynamicSessionId = `issue-test-${randomUUID()}`
-})
-
-afterEach(() => {
-  rmSync(tmpDir, { recursive: true, force: true })
-  delete process.env.CLAUDE_CONFIG_DIR
-  // Restore HOME — individual tests may have set it to tmpDir.
-  if (_originalHomeForIssueSuite === undefined) {
-    delete process.env.HOME
-  } else {
-    process.env.HOME = _originalHomeForIssueSuite
-  }
-})
-
-// After this suite finishes, switch off our dynamic mode so any subsequent
-// test file (e.g. launchAutofixPr.test.ts) that imports bootstrap/state.js
-// gets the static values its suite expects. Bun's mock.module is global and
-// our mock won the registration race; this flag flips behavior post-suite.
-afterAll(() => {
-  useIssueDynamicState = false
-})
-
-// ── Helpers ──
-type CallFn = (
-  args: string,
-  ctx?: never,
-) => Promise<{ type: string; value: string }>
-
-async function getCallFn(): Promise<CallFn> {
-  const mod = await import('../index.js')
-  const loaded = await (
-    mod.default as unknown as { load: () => Promise<{ call: CallFn }> }
-  ).load()
-  return loaded.call.bind(loaded) as CallFn
-}
-
-async function writeSessionLog(entries?: string[]): Promise<void> {
-  const { sanitizePath } = await import('../../../utils/path.js')
-  const { getSessionId, getOriginalCwd } = await import(
-    '../../../bootstrap/state.js'
-  )
-  const sessionId = getSessionId()
-  const cwd = getOriginalCwd()
-  const encoded = sanitizePath(cwd)
-  const dir = join(claudeDir, 'projects', encoded)
-  mkdirSync(dir, { recursive: true })
-  const content = entries ?? [
-    JSON.stringify({ role: 'user', content: 'Fix the login bug' }),
-    JSON.stringify({
-      role: 'assistant',
-      content: [{ type: 'text', text: 'I will investigate' }],
-    }),
-  ]
-  writeFileSync(join(dir, `${sessionId}.jsonl`), content.join('\n') + '\n')
-}
-
-describe('issue command — metadata', () => {
-  test('command has correct name and type', async () => {
-    const mod = await import('../index.js')
-    const cmd = mod.default
-    expect(cmd.name).toBe('issue')
-    expect(cmd.type).toBe('local')
-    expect(
-      (cmd as unknown as { supportsNonInteractive: boolean })
-        .supportsNonInteractive,
-    ).toBe(true)
-  })
-
-  test('isEnabled returns true', async () => {
-    const mod = await import('../index.js')
-    expect(mod.default.isEnabled?.()).toBe(true)
-  })
-})
-
-describe('issue command — parseIssueArgs', () => {
-  test('--label without value → parse error message', async () => {
-    const call = await getCallFn()
-    const result = await call('--label')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('--label requires a value')
-  })
-
-  test('--label with empty next flag → parse error', async () => {
-    const call = await getCallFn()
-    const result = await call('--label --public')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('--label requires a value')
-  })
-
-  test('--assignee without value → parse error message', async () => {
-    const call = await getCallFn()
-    const result = await call('--assignee')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('--assignee requires a value')
-  })
-
-  test('-l without value → parse error', async () => {
-    const call = await getCallFn()
-    const result = await call('-l')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('--label requires a value')
-  })
-
-  test('-a without value → parse error', async () => {
-    const call = await getCallFn()
-    const result = await call('-a')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('--assignee requires a value')
-  })
-
-  test('unknown flag → parse error', async () => {
-    const call = await getCallFn()
-    const result = await call('--unknown Fix bug')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Unknown flag')
-  })
-})
-
-describe('issue command — no title', () => {
-  test('empty args → usage hint', async () => {
-    const call = await getCallFn()
-    const result = await call('')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Usage')
-  })
-
-  test('whitespace-only args → usage hint', async () => {
-    const call = await getCallFn()
-    const result = await call('   ')
-    expect(result.type).toBe('text')
-    expect(result.value).toContain('Usage')
-  })
-})
-
-describe('issue command — with title', () => {
-  test('title only → returns some text result', async () => {
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-    expect(result.value.length).toBeGreaterThan(0)
-  })
-
-  test('title with --label → returns some text result', async () => {
-    const call = await getCallFn()
-    const result = await call('--label bug Fix login bug')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-    expect(result.value.length).toBeGreaterThan(0)
-  })
-
-  test('title with --assignee → returns some text result', async () => {
-    const call = await getCallFn()
-    const result = await call('--assignee alice Fix login bug')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-    expect(result.value.length).toBeGreaterThan(0)
-  })
-
-  test('title with both --label and --assignee → returns some text result', async () => {
-    const call = await getCallFn()
-    const result = await call('--label bug --assignee alice Fix login bug')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-    expect(result.value.length).toBeGreaterThan(0)
-  })
-
-  test('title with log file present → exercises transcript summary paths', async () => {
-    await writeSessionLog()
-    const call = await getCallFn()
-    const result = await call('Fix login bug')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-    expect(result.value.length).toBeGreaterThan(0)
-  })
-
-  test('transcript with array content → covers array branch in getTranscriptSummary', async () => {
-    await writeSessionLog([
-      JSON.stringify({
-        role: 'user',
-        content: [{ type: 'text', text: 'What is the issue?' }],
-      }),
-      // tool_result with is_error → covers error collection
-      JSON.stringify({
-        role: 'user',
-        content: [
-          {
-            type: 'tool_result',
-            tool_use_id: 'tu1',
-            is_error: true,
-            content: 'Command failed',
-          },
-        ],
-      }),
-      // malformed line
-      'NOT_JSON{{{',
-    ])
-    const call = await getCallFn()
-    const result = await call('Test issue')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-  })
-
-  test('transcript with only system entries → no conversation content', async () => {
-    await writeSessionLog([
-      JSON.stringify({ role: 'system', content: 'system prompt' }),
-    ])
-    const call = await getCallFn()
-    const result = await call('Test issue empty summary')
-    expect(result.type).toBe('text')
-    expect(typeof result.value).toBe('string')
-  })
-
-  // ── H5 regression: browser fallback URL body must be ≤ 4096 chars before encode ──
-  test('H5: URL-encoded body is capped at 4096 chars when session summary is very long', async () => {
-    // Write a log with a very long user message to ensure summary exceeds 4096 chars
-    const longText = 'A'.repeat(6000)
-    await writeSessionLog([
-      JSON.stringify({ role: 'user', content: longText }),
-      JSON.stringify({
-        role: 'assistant',
-        content: [{ type: 'text', text: longText }],
-      }),
-    ])
-    const call = await getCallFn()
-    // No gh, no remote → falls into browser fallback path
-    const result = await call('Some Long Issue Title')
-    expect(result.type).toBe('text')
-    if (result.type === 'text') {
-      // Extract the URL from the output (if present)
-      const urlMatch = result.value.match(/https?:\/\/\S+/)
-      if (urlMatch) {
-        // The URL must be ≤ ~8KB after encoding. Check the body= parameter specifically.
-        const bodyParam = urlMatch[0].match(/[?&]body=([^&]*)/)
-        if (bodyParam) {
-          // decoded body text must be ≤ 4096 chars (plus truncation suffix)
-          const decoded = decodeURIComponent(bodyParam[1])
-          expect(decoded.length).toBeLessThanOrEqual(4096 + 60) // 60 for truncation suffix
-        }
-      }
-    }
-  })
-
-  test('long body session log does not crash', async () => {
-    // Long session log content exercises the body-formatting branches.
-    const longText = 'x'.repeat(4500)
-    const entries: string[] = []
-    for (let i = 0; i < 50; i++) {
-      entries.push(JSON.stringify({ role: 'user', content: longText }))
-      entries.push(
-        JSON.stringify({
-          role: 'assistant',
-          content: [{ type: 'text', text: longText }],
-        }),
-      )
-    }
-    await writeSessionLog(entries)
-    process.env.HOME = tmpDir
-    const call = await getCallFn()
-    const result = await call('Long body issue')
-    expect(result.type).toBe('text')
-  })
-
-  test('handles unreadable session log gracefully', async () => {
-    // Write a corrupt log file that triggers parse errors but exists
-    const { sanitizePath } = await import('../../../utils/path.js')
-    const { getSessionId, getOriginalCwd } = await import(
-      '../../../bootstrap/state.js'
-    )
-    const sessionId = getSessionId()
-    const cwd = getOriginalCwd()
-    const encoded = sanitizePath(cwd)
-    const dir = join(claudeDir, 'projects', encoded)
-    mkdirSync(dir, { recursive: true })
-    // Empty / whitespace-only file: should not crash, will produce empty session text
-    writeFileSync(join(dir, `${sessionId}.jsonl`), '')
-    const call = await getCallFn()
-    const result = await call('Issue from empty session')
-    expect(result.type).toBe('text')
-  })
-
-  test('template directory unreadable returns null template (graceful)', async () => {
-    // Create issue-templates directory with no .md files (only a non-readable subfile name)
-    const templatesDir = join(claudeDir, 'issue-templates')
-    mkdirSync(templatesDir, { recursive: true })
-    writeFileSync(join(templatesDir, 'README.txt'), 'not a markdown template')
-    await writeSessionLog()
-    const call = await getCallFn()
-    // Should still succeed without template — template loading is best-effort
-    const result = await call('Issue without templates')
-    expect(result.type).toBe('text')
-  })
-
-  test('session log read failure caught (path is a directory)', async () => {
-    const { sanitizePath } = await import('../../../utils/path.js')
-    const { getSessionId, getOriginalCwd } = await import(
-      '../../../bootstrap/state.js'
-    )
-    const sessionId = getSessionId()
-    const cwd = getOriginalCwd()
-    const encoded = sanitizePath(cwd)
-    const dir = join(claudeDir, 'projects', encoded)
-    mkdirSync(dir, { recursive: true })
-    // Create a directory at the log path so readFileSync throws EISDIR.
-    mkdirSync(join(dir, `${sessionId}.jsonl`), { recursive: true })
-    const call = await getCallFn()
-    const result = await call('Issue with broken log')
-    expect(result.type).toBe('text')
-    if (result.type === 'text') {
-      // Should still produce output even when session log is unreadable
-      expect(result.value.length).toBeGreaterThan(0)
-    }
-  })
-
-  test('detectIssueTemplate picks up first .md template from .github/ISSUE_TEMPLATE', async () => {
-    // Issue command uses getOriginalCwd() (NOT process.cwd) — override via
-    // setOriginalCwd. Restore after to avoid polluting other tests.
-    const { getOriginalCwd, setOriginalCwd } = await import(
-      '../../../bootstrap/state.js'
-    )
-    const githubDir = join(tmpDir, '.github', 'ISSUE_TEMPLATE')
-    mkdirSync(githubDir, { recursive: true })
-    writeFileSync(
-      join(githubDir, 'bug.md'),
-      '---\nname: Bug\nabout: Bug report\n---\n## Steps to reproduce\n\nSteps...\n',
-    )
-    writeFileSync(
-      join(githubDir, 'config.yml'),
-      'blank_issues_enabled: false\n',
-    )
-    await writeSessionLog()
-    const origCwd = getOriginalCwd()
-    try {
-      setOriginalCwd(tmpDir)
-      const call = await getCallFn()
-      const result = await call('Issue with bug template')
-      expect(result.type).toBe('text')
-    } finally {
-      setOriginalCwd(origCwd)
-    }
-  })
-
-  test('detectIssueTemplate returns null when only non-md templates present', async () => {
-    const { getOriginalCwd, setOriginalCwd } = await import(
-      '../../../bootstrap/state.js'
-    )
-    const githubDir = join(tmpDir, '.github', 'ISSUE_TEMPLATE')
-    mkdirSync(githubDir, { recursive: true })
-    writeFileSync(join(githubDir, 'bug.yml'), 'name: Bug')
-    await writeSessionLog()
-    const origCwd = getOriginalCwd()
-    try {
-      setOriginalCwd(tmpDir)
-      const call = await getCallFn()
-      const result = await call('Issue YAML-only template')
-      expect(result.type).toBe('text')
-    } finally {
-      setOriginalCwd(origCwd)
-    }
-  })
-
-  test('detectIssueTemplate returns null when ISSUE_TEMPLATE is empty', async () => {
-    const { getOriginalCwd, setOriginalCwd } = await import(
-      '../../../bootstrap/state.js'
-    )
-    const githubDir = join(tmpDir, '.github', 'ISSUE_TEMPLATE')
-    mkdirSync(githubDir, { recursive: true })
-    await writeSessionLog()
-    const origCwd = getOriginalCwd()
-    try {
-      setOriginalCwd(tmpDir)
-      const call = await getCallFn()
-      const result = await call('Issue empty template dir')
-      expect(result.type).toBe('text')
-    } finally {
-      setOriginalCwd(origCwd)
-    }
-  })
-
-  test('detectIssueTemplate readdir failure is caught (catch branch)', async () => {
-    const { getOriginalCwd, setOriginalCwd } = await import(
-      '../../../bootstrap/state.js'
-    )
-    // Create the ISSUE_TEMPLATE path as a regular file (not a directory) so
-    // existsSync returns true but readdirSync throws ENOTDIR.
-    const githubDir = join(tmpDir, '.github')
-    mkdirSync(githubDir, { recursive: true })
-    writeFileSync(join(githubDir, 'ISSUE_TEMPLATE'), 'not-a-directory')
-    await writeSessionLog()
-    const origCwd = getOriginalCwd()
-    try {
-      setOriginalCwd(tmpDir)
-      const call = await getCallFn()
-      const result = await call('Issue with broken template path')
-      expect(result.type).toBe('text')
-    } finally {
-      setOriginalCwd(origCwd)
-    }
-  })
-
-  test('long body triggers truncation + draft save', async () => {
-    const { getOriginalCwd, setOriginalCwd } = await import(
-      '../../../bootstrap/state.js'
-    )
-    // getTranscriptSummary clips each user/assistant text to 200 chars and
-    // joins only the last 10 entries, so it can never organically exceed
-    // ~2.7 KB. To exercise the >4096-char branch (lines 362-375), we
-    // temporarily neutralise Array.prototype.slice for the `slice(-N)`
-    // pattern (negative-only first arg, no second arg). String.slice and
-    // positive Array.slice keep working, and we restore the original in
-    // finally so no state leaks across tests.
-    const longText = 'x'.repeat(200)
-    const entries: string[] = []
-    for (let i = 0; i < 100; i++) {
-      entries.push(JSON.stringify({ role: 'user', content: longText }))
-      entries.push(
-        JSON.stringify({
-          role: 'assistant',
-          content: [{ type: 'text', text: longText }],
-        }),
-      )
-    }
-    await writeSessionLog(entries)
-    process.env.HOME = tmpDir
-    const origCwd = getOriginalCwd()
-    const origSlice = Array.prototype.slice
-    // Force the fallback URL branch with a *parsed* GitHub remote so the
-    // draft-path output (lines 392-393) is reached: git remote returns a
-    // GitHub URL but `gh --version` fails so hasGh is false.
-    //
-    // Spread+flag pattern: the previous bare `mock.module(...)` here leaked
-    // a stub child_process to every later test file in the same `bun test`
-    // run (mock.module is process-global, last-write-wins). Now we register
-    // a flag-gated mock that delegates to real child_process by default, and
-    // only flips on for THIS test's body.
-    mock.module('node:child_process', () => {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      const real = require('node:child_process') as Record<string, unknown>
-      return {
-        ...real,
-        default: real,
-        execFile: ((...args: unknown[]) => {
-          if (useIssueLongBodyCpStubs) {
-            const cb = args[3] as
-              | ((e: Error | null, s: string, e2: string) => void)
-              | undefined
-            if (cb) cb(new Error('ENOENT'), '', '')
-            return
-          }
-          return (real.execFile as (...a: unknown[]) => unknown)(...args)
-        }) as typeof real.execFile,
-        execFileSync: ((...args: unknown[]) => {
-          if (useIssueLongBodyCpStubs) {
-            const cmd = args[0] as string
-            if (cmd === 'git')
-              return Buffer.from('https://github.com/owner/repo.git\n')
-            throw new Error('ENOENT')
-          }
-          return (real.execFileSync as (...a: unknown[]) => unknown)(...args)
-        }) as typeof real.execFileSync,
-      }
-    })
-    useIssueLongBodyCpStubs = true
-    Array.prototype.slice = function (
-      this: unknown[],
-      start?: number,
-      end?: number,
-    ): unknown[] {
-      // For `summaryParts.slice(-10)` and `errors.slice(-3)` (negative
-      // start, no end) return the full array so summaryParts.length
-      // determines the body size.
-      if (typeof start === 'number' && start < 0 && end === undefined) {
-        return Array.from(this)
-      }
-      return origSlice.call(this, start, end) as unknown[]
-    } as typeof Array.prototype.slice
-    try {
-      setOriginalCwd(tmpDir)
-      const call = await getCallFn()
-      const result = await call('Long body for draft save')
-      expect(result.type).toBe('text')
-      if (result.type === 'text') {
-        // Draft path is reported when body > 4096 chars (line 393 branch).
-        expect(result.value).toContain('Full issue body saved to')
-      }
-    } finally {
-      Array.prototype.slice = origSlice
-      setOriginalCwd(origCwd)
-      useIssueLongBodyCpStubs = false
-    }
-  })
-})

src/commands/login/getAuthStatus.ts

@@ -11,6 +11,7 @@
  *   - Third-party API key values are NEVER included; only boolean presence flags.
  */
 
+import type { SubscriptionType } from '../../services/oauth/types.js'
 import { getClaudeAIOAuthTokens } from '../../utils/auth.js'
 import { getGlobalConfig } from '../../utils/config.js'
 
@@ -107,7 +108,10 @@ export function getAuthStatus(): AuthStatus {
 
   let plan: AuthStatus['subscription']['plan'] = null
   if (subscriptionActive && oauthTokens) {
-    const raw = oauthTokens.subscriptionType
+    // 本地持久化或历史 token 中可能出现 'free' 等未纳入 SubscriptionType 的字符串
+    const raw = oauthTokens.subscriptionType as
+      | (SubscriptionType | 'free')
+      | null
     if (
       raw === 'free' ||
       raw === 'pro' ||