fix: normalizeMessagesForAPI 不再跨 tool_result 边界合并同 ID assistant 消息 (CC-1215)

ACP 模式下 extended thinking + tool_use 同一 turn 时，StreamingToolExecutor
在两个同 message.id 的 AssistantMessage 之间插入 tool_result，导致向后遍历
合并跨越边界，产生重复 tool_use ID → 孤立 tool_result → 连续 user 消息 → 400。

修改向后遍历停止条件：遇到非 assistant 消息（含 tool_result）即停止，不再跳过。

.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/ci.yml

@@ -42,7 +42,8 @@ jobs:
         run: |
           # Tolerate pre-existing flaky tests (Bun mock pollution / order-dependent state).
           # We still require lcov.info to be generated and contain real coverage data.
-          bun test --coverage --coverage-reporter lcov --coverage-dir coverage 2>&1 | grep -vE '^\s*(\(pass\)|\(skip\))' | sed '/^.*\/__tests__\/.*:$/d' | cat -s || true
+          set -o pipefail
+          bun test --coverage --coverage-reporter lcov --coverage-dir coverage 2>&1 | grep -vE '^\s*(\(pass\)|\(skip\))' | sed '/^.*\/__tests__\/.*:$/d' | cat -s
           test -s coverage/lcov.info
           grep -q '^SF:' coverage/lcov.info
 

.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,15 +78,16 @@ 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 — 15 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。
+- **Monorepo**: Bun workspaces — 17 个 workspace packages + 若干辅助目录 in `packages/` resolved via `workspace:*`。
 - **Lint/Format**: Biome (`biome.json`)。覆盖 `src/`、`scripts/`、`packages/` 全项目（含 `packages/@ant/`）。`bun run lint` / `bun run lint:fix` / `bun run format` / `bun run check` / `bun run check:fix`。42 条规则因 decompiled 代码被关闭，仅保留 `recommended` 基线。
 - **Pre-commit**: husky + lint-staged。提交时自动对暂存文件执行 `biome check --fix`（TS/JS）和 `biome format --write`（JSON）。
 - **CI Lint**: `ci.yml` 在依赖安装后、类型检查前执行 `bunx biome ci .`，lint 或格式化不达标则 CI 失败。
-- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.1.888`。
+- **Defines**: 集中管理在 `scripts/defines.ts`。当前版本 `2.2.1`。
 - **CI**: GitHub Actions — `ci.yml`（lint + 构建 + 测试）、`release-rcs.yml`（RCS 发布）、`update-contributors.yml`（自动更新贡献者）。
 
 ### Entry & Bootstrap
@@ -104,7 +105,7 @@ bun run docs:dev
    - `environment-runner` / `self-hosted-runner` — BYOC runner
    - `--tmux` + `--worktree` 组合
    - 默认路径：加载 `main.tsx` 启动完整 CLI
-2. **`src/main.tsx`** (~6981 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
+2. **`src/main.tsx`** (~5674 行) — Commander.js CLI definition。注册大量 subcommands：`mcp` (serve/add/remove/list...)、`server`、`ssh`、`open`、`auth`、`plugin`、`agents`、`auto-mode`、`doctor`、`update` 等。主 `.action()` 处理器负责权限、MCP、会话恢复、REPL/Headless 模式分发。
 3. **`src/entrypoints/init.ts`** — One-time initialization (telemetry, config, trust dialog)。
 
 ### Core Loop
@@ -123,17 +124,18 @@ bun run docs:dev
 
 - **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`).
 - **`src/tools.ts`** — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`.
-- **`src/constants/tools.ts`** — `CORE_TOOLS` 白名单常量（约 29 个核心工具名），用于 `isDeferredTool` 白名单制判定。
-- **`packages/builtin-tools/src/tools/`** — 59 个子目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：
+- **`src/constants/tools.ts`** — `CORE_TOOLS` 白名单常量（38 个核心工具名），用于 `isDeferredTool` 白名单制判定。
+- **`packages/builtin-tools/src/tools/`** — 60 个工具目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类：
   - **文件操作**: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool
   - **Shell/执行**: BashTool, PowerShellTool, REPLTool
   - **Agent 系统**: AgentTool, TaskCreateTool, TaskUpdateTool, TaskListTool, TaskGetTool
   - **规划**: EnterPlanModeTool, ExitPlanModeV2Tool, VerifyPlanExecutionTool
   - **Web/MCP**: WebFetchTool, WebSearchTool, MCPTool, McpAuthTool
   - **调度**: CronCreateTool, CronDeleteTool, CronListTool
+  - **工具发现**: SearchExtraToolsTool, ExecuteExtraTool, SyntheticOutput（CORE_TOOLS，用于延迟工具按需加载）
   - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等
 - **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。
-- **`src/services/searchExtraTools/`** — TF-IDF 工具索引模块（`toolIndex.ts`），为延迟工具提供语义搜索能力。复用 `localSearch.ts` 的 TF-IDF 算法函数（`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 已导出）。修改这些函数时需同步检查工具索引测试。`SearchExtraToolsTool.mapToolResultToToolResultBlockParam` 新增可选第三个参数 `context?: { mainLoopModel?: string }`，用于判断当前模型是否支持 `tool_reference`。不支持时回退到文本输出，引导模型使用 ExecuteTool。调用方（`src/services/api/claude.ts` 的 tool_result 处理逻辑）需传入 context 参数。`prefetch.ts` 的 `extractQueryFromMessages` 复用了 `skillSearch/prefetch.ts` 的同名导出函数，修改 skill prefetch 的该函数时需同步检查工具预取行为。工具预取使用独立的 `discoveredToolsThisSession` Set，与 skill prefetch 的去重集合互不影响。
+- **`src/services/searchExtraTools/`** — TF-IDF 工具索引模块（`toolIndex.ts`），为延迟工具提供语义搜索能力。复用 `localSearch.ts` 的 TF-IDF 算法函数（`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 已导出）。修改这些函数时需同步检查工具索引测试。`prefetch.ts` 的 `extractQueryFromMessages` 复用了 `skillSearch/prefetch.ts` 的同名导出函数，修改 skill prefetch 的该函数时需同步检查工具预取行为。工具预取使用独立的 `discoveredToolsThisSession` Set，与 skill prefetch 的去重集合互不影响。
 
 ### UI Layer (Ink)
 
@@ -168,18 +170,16 @@ bun run docs:dev
 | `packages/builtin-tools/` | 内置工具集（60 个 tool 实现，通过 `@claude-code-best/builtin-tools` 导出） |
 | `packages/agent-tools/` | Agent 工具集 |
 | `packages/acp-link/` | ACP 代理服务器（WebSocket → ACP agent 桥接） |
-| `packages/cc-knowledge/` | Claude Code 知识库（非 workspace 包） |
-| `packages/langfuse-dashboard/` | Langfuse 可观测性面板（非 workspace 包） |
 | `packages/mcp-client/` | MCP 客户端库 |
-| `packages/mcp-server/` | MCP 服务端库（非 workspace 包） |
 | `packages/remote-control-server/` | 自托管 Remote Control Server（Docker 部署，含 Web UI）— Web UI 已重构为 React + Vite + Radix UI，支持 ACP agent 接入 |
-| `packages/swarm/` | Swarm 解耦模块（非 workspace 包） |
-| `packages/shell/` | Shell 抽象（非 workspace 包） |
 | `packages/audio-capture-napi/` | 原生音频捕获（已恢复） |
 | `packages/color-diff-napi/` | 颜色差异计算（完整实现，11 tests） |
 | `packages/image-processor-napi/` | 图像处理（已恢复） |
 | `packages/modifiers-napi/` | 键盘修饰键检测（macOS FFI 实现） |
 | `packages/url-handler-napi/` | URL scheme 处理（环境变量 + CLI 参数读取） |
+| `packages/weixin/` | 微信集成（非 workspace 包） |
+
+辅助目录（无 package.json，非 workspace 包）: `langfuse-dashboard`（Langfuse 面板）、`shared-web-ui`（共享 Web UI 组件）、`highlight-code`（代码高亮）、`claude-pencil`（编辑器）、`vscode-ide-bridge`（VS Code 桥接）、`pokemon`（示例/测试）。
 
 ### Bridge / Remote Control
 
@@ -210,12 +210,18 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 
 **启用方式**: 环境变量 `FEATURE_<FLAG_NAME>=1`。例如 `FEATURE_BUDDY=1 bun run dev`。
 
-**Build 默认 features**（19 个，见 `build.ts`）:
+**Build 默认 features**（65+ 个，见 `build.ts` 中 `DEFAULT_BUILD_FEATURES`）:
 - 基础: `BUDDY`, `TRANSCRIPT_CLASSIFIER`, `BRIDGE_MODE`, `AGENT_TRIGGERS_REMOTE`, `CHICAGO_MCP`, `VOICE_MODE`
 - 统计/缓存: `SHOT_STATS`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`
 - P0 本地: `AGENT_TRIGGERS`, `ULTRATHINK`, `BUILTIN_EXPLORE_PLAN_AGENTS`, `LODESTONE`
 - P1 API 依赖: `EXTRACT_MEMORIES`, `VERIFICATION_AGENT`, `KAIROS_BRIEF`, `AWAY_SUMMARY`, `ULTRAPLAN`
-- P2: `DAEMON`
+- P2: `DAEMON`, `ACP`
+- 工作流: `WORKFLOW_SCRIPTS`, `HISTORY_SNIP`, `MONITOR_TOOL`, `KAIROS`
+- 多 worker: `COORDINATOR_MODE`, `BG_SESSIONS`, `TEMPLATES`
+- 连接器: `CONNECTOR_TEXT`, `COMMIT_ATTRIBUTION`, `DIRECT_CONNECT`
+- 实验性: `EXPERIMENTAL_SKILL_SEARCH`, `EXPERIMENTAL_SEARCH_EXTRA_TOOLS`
+- 模式: `POOR`, `SSH_REMOTE`
+- 已禁用: `CONTEXT_COLLAPSE`, `FORK_SUBAGENT`, `UDS_INBOX`, `LAN_PIPES`, `REVIEW_ARTIFACT`, `TEAMMEM`, `SKILL_LEARNING`
 
 **Dev mode 默认**: 全部启用（见 `scripts/dev.ts`）。
 
@@ -265,6 +271,7 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 | Voice Mode | Restored — Push-to-Talk 语音输入（需 Anthropic OAuth） |
 | OpenAI/Gemini/Grok 兼容层 | Restored |
 | Remote Control Server | Restored — 自托管 RCS + Web UI |
+| `packages/shell/`, `packages/swarm/`, `packages/mcp-server/`, `packages/cc-knowledge/` | Removed — 功能合并或废弃 |
 | Analytics / GrowthBook / Sentry | Empty implementations |
 | Magic Docs / LSP Server | Restored — Magic Docs 自动更新 + LSP 服务器管理器 |
 | Plugins / Marketplace | Restored — 插件安装/卸载/启用/禁用 + Marketplace 浏览 |
@@ -281,7 +288,7 @@ Feature flags control which functionality is enabled at runtime. 代码中统一
 
 - **框架**: `bun:test`（内置断言 + mock）
 - **单元测试**: 就近放置于 `src/**/__tests__/`，文件名 `<module>.test.ts`
-- **集成测试**: `tests/integration/` — 4 个文件（cli-arguments, context-build, message-pipeline, tool-chain）
+- **集成测试**: `tests/integration/` — 6 个文件（cli-arguments, context-build, message-pipeline, tool-chain, autonomy-lifecycle-user-flow, dependency-overrides）
 - **共享 mock/fixture**: `tests/mocks/`（api-responses, file-system, fixtures/）
 - **命名**: `describe("functionName")` + `test("behavior description")`，英文
 - **包测试**: `packages/` 下各包也有独立测试（如 `color-diff-napi` 11 tests）
@@ -308,6 +315,48 @@ mock.module("src/utils/debug.ts", debugMock);
 
 路径规则：统一用 `.ts` 扩展名 + `src/*` 别名路径，禁止双重 mock 同一模块。
 
+#### 跨文件 mock 污染（process-global `mock.module`）
+
+**Bun 的 `mock.module` 是进程全局的（last-write-wins），不是 per-file 隔离的。** 一个测试文件的 `mock.module` 会污染同一进程中所有其他测试文件的 `require`/`import`。
+
+**关键事实（Bun 1.x 实测验证）：**
+- 测试文件执行顺序**不是严格字母序**，不要假设文件 A 一定在文件 B 之前执行。
+- `mock.module` 在 `beforeAll` 内部调用时**不会被提升**（hoist），但仍会污染后续加载的文件。
+- `require()` 和 `import()` 共享同一模块注册表，`mock.module` 对两者都生效。
+- 一个模块一旦被某个文件的 `mock.module` 替换，同一进程中所有后续 `require`/`import` 都会返回 mock 值，即使调用方使用不同的 specifier 路径。
+
+**核心规则：不要 mock 被测模块的上层业务模块。**
+
+错误做法（会污染同目录的 `api.test.ts`）：
+```ts
+// launchSchedule.test.ts — 直接 mock 源 API 模块 ❌
+mock.module('src/commands/schedule/triggersApi.js', () => ({
+  listTriggers: listTriggersMock,
+  // ...
+}))
+```
+
+正确做法（mock 底层 HTTP 层，不污染业务模块）：参考 `launchSkillStore.test.ts`、`launchVault.test.ts` 的模式。
+```ts
+// launchSchedule.test.ts — mock axios 而非 triggersApi ✅
+import { setupAxiosMock } from '../../../../tests/mocks/axios.js'
+
+const axiosHandle = setupAxiosMock()
+axiosHandle.stubs.get = axiosGetMock
+axiosHandle.stubs.post = axiosPostMock
+
+beforeAll(() => { axiosHandle.useStubs = true })
+afterAll(() => { axiosHandle.useStubs = false })
+```
+
+**判断标准：** 如果目录下同时有 `launch*.test.ts`（集成测试）和 `api.test.ts`（回归测试），`launch*.test.ts` 必须 mock axios 而非源 API 模块。`api.test.ts` 需要测试真实 API 模块的 HTTP 方法/URL/错误处理逻辑，被 mock 后就无法测试。
+
+**排查 mock 污染的方法：**
+1. 单独运行可疑文件确认其通过：`bun test path/to/suspect.test.ts`
+2. 与同目录其他文件一起运行定位污染源：`bun test path/to/__tests__/`
+3. 在两个文件中各加 `console.error('[file] milestone')` 追踪实际执行顺序
+4. 检查 `mock.module` 的 specifier 是否与同目录其他测试的 `require`/`import` 路径解析到同一模块
+
 ### 类型检查
 
 项目使用 TypeScript strict 模式，**tsc 必须零错误**。每次修改后运行：

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/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.2.1",
+  "version": "2.6.6",
   "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/__tests__/prompt.test.ts

@@ -57,13 +57,4 @@ describe('prompt.ts fork-related text verification', () => {
       expect(bgCondition[0]).not.toContain('!forkEnabled')
     }
   })
-
-  test('fork example includes fork: true parameter', () => {
-    // The first fork example should have fork: true
-    const forkExampleBlock = promptSource.match(
-      /name: "ship-audit"[\s\S]*?Under 200 words/,
-    )
-    expect(forkExampleBlock).not.toBeNull()
-    expect(forkExampleBlock![0]).toContain('fork: true')
-  })
 })

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/prompt.ts

@@ -5,7 +5,6 @@ import { isEnvDefinedFalsy, isEnvTruthy } from 'src/utils/envUtils.js'
 import { isTeammate } from 'src/utils/teammate.js'
 import { isInProcessTeammate } from 'src/utils/teammateContext.js'
 import { FILE_READ_TOOL_NAME } from '../FileReadTool/prompt.js'
-import { FILE_WRITE_TOOL_NAME } from '../FileWriteTool/prompt.js'
 import { GLOB_TOOL_NAME } from '../GlobTool/prompt.js'
 import { SEND_MESSAGE_TOOL_NAME } from '../SendMessageTool/constants.js'
 import { AGENT_TOOL_NAME } from './constants.js'
@@ -84,11 +83,11 @@ export async function getPrompt(
 
 When you need to delegate work that benefits from full conversation context (e.g., continuing a multi-file refactor where the child needs the same system prompt and history), use \`fork: true\`. For most tasks, prefer specialized agent types (Explore, Plan, general-purpose).
 
-**Don't peek.** The tool result includes an \`output_file\` path — do not Read or tail it unless the user explicitly asks for a progress check. You get a completion notification; trust it. Reading the transcript mid-flight pulls the fork's tool noise into your context, which defeats the point of forking.
+**Don't peek.** The tool result includes an \`output_file\` path — do not Read or tail it unless the user explicitly asks for a progress check. You get a completion notification; trust it.
 
-**Don't race.** After launching, you know nothing about what the fork found. Never fabricate or predict fork results in any format — not as prose, summary, or structured output. The notification arrives as a user-role message in a later turn; it is never something you write yourself. If the user asks a follow-up before the notification lands, tell them the fork is still running — give status, not a guess.
+**Don't race.** After launching, you know nothing about what the fork found. Never fabricate or predict fork results. If the user asks a follow-up before the notification lands, tell them the fork is still running.
 
-**Writing a fork prompt.** Since the fork inherits your context, the prompt is a *directive* — what to do, not what the situation is. Be specific about scope: what's in, what's out, what another agent is handling. Don't re-explain background.
+**Writing a fork prompt.** Since the fork inherits your context, the prompt is a *directive* — what to do, not what the situation is. Be specific about scope. Don't re-explain background.
 `
     : ''
 
@@ -97,91 +96,13 @@ When you need to delegate work that benefits from full conversation context (e.g
 ## Writing the prompt
 
 ${forkEnabled ? 'When spawning an agent without `fork: true`, it starts with zero context. ' : ''}Brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
-- Explain what you're trying to accomplish and why.
-- Describe what you've already learned or ruled out.
-- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- Explain what you're trying to accomplish and why, what you've already learned or ruled out, and enough context for the agent to make judgment calls.
 - If you need a short response, say so ("report in under 200 words").
 - Lookups: hand over the exact command. Investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
 
 ${forkEnabled ? 'For non-fork agents, terse' : 'Terse'} command-style prompts produce shallow, generic work.
 
-**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.
-`
-
-  const forkExamples = `Example usage:
-
-<example>
-user: "What's left on this branch before we can ship?"
-assistant: <thinking>Forking this \u2014 it's a survey question. I want the punch list, not the git output in my context.</thinking>
-${AGENT_TOOL_NAME}({
-  name: "ship-audit",
-  description: "Branch ship-readiness audit",
-  fork: true,
-  prompt: "Audit what's left before this branch can ship. Check: uncommitted changes, commits ahead of main, whether tests exist, whether the GrowthBook gate is wired up, whether CI-relevant files changed. Report a punch list \u2014 done vs. missing. Under 200 words."
-})
-assistant: Ship-readiness audit running.
-<commentary>
-Turn ends here. The coordinator knows nothing about the findings yet. What follows is a SEPARATE turn \u2014 the notification arrives from outside, as a user-role message. It is not something the coordinator writes.
-</commentary>
-[later turn \u2014 notification arrives as user message]
-assistant: Audit's back. Three blockers: no tests for the new prompt path, GrowthBook gate wired but not in build_flags.yaml, and one uncommitted file.
-</example>
-
-<example>
-user: "so is the gate wired up or not"
-<commentary>
-User asks mid-wait. The audit fork was launched to answer exactly this, and it hasn't returned. The coordinator does not have this answer. Give status, not a fabricated result.
-</commentary>
-assistant: Still waiting on the audit \u2014 that's one of the things it's checking. Should land shortly.
-</example>
-
-<example>
-user: "Can you get a second opinion on whether this migration is safe?"
-assistant: <thinking>I'll ask the code-reviewer agent — it won't see my analysis, so it can give an independent read.</thinking>
-<commentary>
-A subagent_type is specified, so the agent starts fresh. It needs full context in the prompt. The briefing explains what to assess and why.
-</commentary>
-${AGENT_TOOL_NAME}({
-  name: "migration-review",
-  description: "Independent migration review",
-  subagent_type: "code-reviewer",
-  prompt: "Review migration 0042_user_schema.sql for safety. Context: we're adding a NOT NULL column to a 50M-row table. Existing rows get a backfill default. I want a second opinion on whether the backfill approach is safe under concurrent writes — I've checked locking behavior but want independent verification. Report: is this safe, and if not, what specifically breaks?"
-})
-</example>
-`
-
-  const currentExamples = `Example usage:
-
-<example_agent_descriptions>
-"test-runner": use this agent after you are done writing code to run tests
-"greeting-responder": use this agent to respond to user greetings with a friendly joke
-</example_agent_descriptions>
-
-<example>
-user: "Please write a function that checks if a number is prime"
-assistant: I'm going to use the ${FILE_WRITE_TOOL_NAME} tool to write the following code:
-<code>
-function isPrime(n) {
-  if (n <= 1) return false
-  for (let i = 2; i * i <= n; i++) {
-    if (n % i === 0) return false
-  }
-  return true
-}
-</code>
-<commentary>
-Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
-</commentary>
-assistant: Uses the ${AGENT_TOOL_NAME} tool to launch the test-runner agent
-</example>
-
-<example>
-user: "Hello"
-<commentary>
-Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
-</commentary>
-assistant: "I'm going to use the ${AGENT_TOOL_NAME} tool to launch the greeting-responder agent"
-</example>
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Write prompts that prove you understood: include file paths, line numbers, what specifically to change.
 `
 
   // When the gate is on, the agent list lives in an agent_listing_delta
@@ -273,7 +194,5 @@ Usage notes:
         ? `
 - The name, team_name, and mode parameters are not available in this context — teammates cannot spawn other teammates. Omit them to spawn a subagent.`
         : ''
-  }${whenToForkSection}${writingThePromptSection}
-
-${forkEnabled ? forkExamples : currentExamples}`
+  }${whenToForkSection}${writingThePromptSection}`
 }

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/prompt.ts

@@ -314,15 +314,13 @@ export function getSimplePrompt(): string {
           'Use the Monitor tool to stream events from a background process (each stdout line is a notification). For one-shot "wait until done," use Bash with run_in_background instead.',
         ]
       : []),
-    'If your command is long running and you would like to be notified when it finishes — use `run_in_background`. No sleep needed.',
+    'For long-running commands, use `run_in_background` — you will be notified when it completes. Do not poll.',
     'Do not retry failing commands in a sleep loop — diagnose the root cause.',
-    'If waiting for a background task you started with `run_in_background`, you will be notified when it completes — do not poll.',
     ...(feature('MONITOR_TOOL')
       ? [
           '`sleep N` as the first command with N ≥ 2 is blocked. If you need a delay (rate limiting, deliberate pacing), keep it under 2 seconds.',
         ]
       : [
-          'If you must poll an external process, use a check command (e.g. `gh run view`) rather than sleeping first.',
           'If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.',
         ]),
   ]

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/EnterPlanModeTool/prompt.ts

@@ -26,33 +26,13 @@ function getEnterPlanModeToolPromptExternal(): string {
 
 **Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
 
-1. **New Feature Implementation**: Adding meaningful new functionality
-   - Example: "Add a logout button" - where should it go? What should happen on click?
-   - Example: "Add form validation" - what rules? What error messages?
-
-2. **Multiple Valid Approaches**: The task can be solved in several different ways
-   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
-   - Example: "Improve performance" - many optimization strategies possible
-
-3. **Code Modifications**: Changes that affect existing behavior or structure
-   - Example: "Update the login flow" - what exactly should change?
-   - Example: "Refactor this component" - what's the target architecture?
-
-4. **Architectural Decisions**: The task requires choosing between patterns or technologies
-   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
-   - Example: "Implement state management" - Redux vs Context vs custom solution
-
-5. **Multi-File Changes**: The task will likely touch more than 2-3 files
-   - Example: "Refactor the authentication system"
-   - Example: "Add a new API endpoint with tests"
-
-6. **Unclear Requirements**: You need to explore before understanding the full scope
-   - Example: "Make the app faster" - need to profile and identify bottlenecks
-   - Example: "Fix the bug in checkout" - need to investigate root cause
-
-7. **User Preferences Matter**: The implementation could reasonably go multiple ways
-   - If you would use ${ASK_USER_QUESTION_TOOL_NAME} to clarify the approach, use EnterPlanMode instead
-   - Plan mode lets you explore first, then present options with context
+1. **New Feature Implementation** — Adding meaningful new functionality where the implementation path isn't obvious
+2. **Multiple Valid Approaches** — The task can be solved in several different ways
+3. **Code Modifications** — Changes that affect existing behavior or structure, where the user should approve the approach
+4. **Architectural Decisions** — The task requires choosing between patterns or technologies
+5. **Multi-File Changes** — The task will likely touch more than 2-3 files
+6. **Unclear Requirements** — You need to explore before understanding the full scope
+7. **User Preferences Matter** — If you would use ${ASK_USER_QUESTION_TOOL_NAME} to clarify the approach, use EnterPlanMode instead
 
 ## When NOT to Use This Tool
 
@@ -62,35 +42,7 @@ Only skip EnterPlanMode for simple tasks:
 - Tasks where the user has given very specific, detailed instructions
 - Pure research/exploration tasks (use the Agent tool with explore agent instead)
 
-${whatHappens}## Examples
-
-### GOOD - Use EnterPlanMode:
-User: "Add user authentication to the app"
-- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
-
-User: "Optimize the database queries"
-- Multiple approaches possible, need to profile first, significant impact
-
-User: "Implement dark mode"
-- Architectural decision on theme system, affects many components
-
-User: "Add a delete button to the user profile"
-- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
-
-User: "Update the error handling in the API"
-- Affects multiple files, user should approve the approach
-
-### BAD - Don't use EnterPlanMode:
-User: "Fix the typo in the README"
-- Straightforward, no planning needed
-
-User: "Add a console.log to debug this function"
-- Simple, obvious implementation
-
-User: "What files handle routing?"
-- Research task, not implementation planning
-
-## Important Notes
+${whatHappens}## Important Notes
 
 - This tool REQUIRES user approval - they must consent to entering plan mode
 - If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
@@ -111,53 +63,23 @@ function getEnterPlanModeToolPromptAnt(): string {
 
 Plan mode is valuable when the implementation approach is genuinely unclear. Use it when:
 
-1. **Significant Architectural Ambiguity**: Multiple reasonable approaches exist and the choice meaningfully affects the codebase
-   - Example: "Add caching to the API" - Redis vs in-memory vs file-based
-   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
-
-2. **Unclear Requirements**: You need to explore and clarify before you can make progress
-   - Example: "Make the app faster" - need to profile and identify bottlenecks
-   - Example: "Refactor this module" - need to understand what the target architecture should be
-
-3. **High-Impact Restructuring**: The task will significantly restructure existing code and getting buy-in first reduces risk
-   - Example: "Redesign the authentication system"
-   - Example: "Migrate from one state management approach to another"
+1. **Significant Architectural Ambiguity** — Multiple reasonable approaches exist and the choice meaningfully affects the codebase
+2. **Unclear Requirements** — You need to explore and clarify before you can make progress
+3. **High-Impact Restructuring** — The task will significantly restructure existing code and getting buy-in first reduces risk
 
 ## When NOT to Use This Tool
 
 Skip plan mode when you can reasonably infer the right approach:
 - The task is straightforward even if it touches multiple files
 - The user's request is specific enough that the implementation path is clear
-- You're adding a feature with an obvious implementation pattern (e.g., adding a button, a new endpoint following existing conventions)
+- You're adding a feature with an obvious implementation pattern
 - Bug fixes where the fix is clear once you understand the bug
 - Research/exploration tasks (use the Agent tool instead)
 - The user says something like "can we work on X" or "let's do X" — just get started
 
 When in doubt, prefer starting work and using ${ASK_USER_QUESTION_TOOL_NAME} for specific questions over entering a full planning phase.
 
-${whatHappens}## Examples
-
-### GOOD - Use EnterPlanMode:
-User: "Add user authentication to the app"
-- Genuinely ambiguous: session vs JWT, where to store tokens, middleware structure
-
-User: "Redesign the data pipeline"
-- Major restructuring where the wrong approach wastes significant effort
-
-### BAD - Don't use EnterPlanMode:
-User: "Add a delete button to the user profile"
-- Implementation path is clear; just do it
-
-User: "Can we work on the search feature?"
-- User wants to get started, not plan
-
-User: "Update the error handling in the API"
-- Start working; ask specific questions if needed
-
-User: "Fix the typo in the README"
-- Straightforward, no planning needed
-
-## Important Notes
+${whatHappens}## Important Notes
 
 - This tool REQUIRES user approval - they must consent to entering plan mode
 `

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

@@ -10,8 +10,14 @@ import {
 } from 'src/Tool.js'
 import { lazySchema } from 'src/utils/lazySchema.js'
 import { createUserMessage } from 'src/utils/messages.js'
+import {
+  extractDiscoveredToolNames,
+  isSearchExtraToolsEnabledOptimistic,
+  isSearchExtraToolsToolAvailable,
+} from 'src/utils/searchExtraTools.js'
 import { DESCRIPTION, getPrompt } from './prompt.js'
 import { EXECUTE_TOOL_NAME } from './constants.js'
+import { isDeferredTool } from '../SearchExtraToolsTool/prompt.js'
 
 export const inputSchema = lazySchema(() =>
   z.object({
@@ -74,6 +80,32 @@ export const ExecuteTool = buildTool({
       }
     }
 
+    // Guard: block execution of undiscovered deferred tools.
+    // When tool search is active, deferred tools must be discovered via
+    // SearchExtraTools first so the model has seen their schemas and knows
+    // the correct parameters.  Executing an undiscovered tool almost always
+    // fails with parameter validation errors.
+    if (
+      isSearchExtraToolsEnabledOptimistic() &&
+      isSearchExtraToolsToolAvailable(tools) &&
+      isDeferredTool(targetTool)
+    ) {
+      const discovered = extractDiscoveredToolNames(context.messages)
+      if (!discovered.has(input.tool_name)) {
+        return {
+          data: {
+            result: null,
+            tool_name: input.tool_name,
+          },
+          newMessages: [
+            createUserMessage({
+              content: `Tool "${input.tool_name}" has not been discovered yet. You must first use SearchExtraTools to discover this tool before executing it.\n\nUsage: SearchExtraTools("select:${input.tool_name}")`,
+            }),
+          ],
+        }
+      }
+    }
+
     // Check if the target tool is currently enabled
     if (!targetTool.isEnabled()) {
       return {
@@ -89,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>,
@@ -132,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.runner.ts

@@ -33,10 +33,10 @@ mock.module('src/utils/searchExtraTools.js', () => ({
   isSearchExtraToolsEnabledOptimistic: () => true,
   getAutoSearchExtraToolsCharThreshold: () => 100,
   getSearchExtraToolsMode: () => 'tst' as const,
-  isSearchExtraToolsToolAvailable: async () => true,
+  isSearchExtraToolsToolAvailable: () => true,
   isSearchExtraToolsEnabled: async () => true,
   isToolReferenceBlock: () => false,
-  extractDiscoveredToolNames: () => new Set(),
+  extractDiscoveredToolNames: () => new Set(['TestTool', 'SecretTool']),
   isDeferredToolsDeltaEnabled: () => false,
   getDeferredToolsDelta: () => null,
 }))
@@ -154,6 +154,26 @@ describe('ExecuteTool', () => {
     expect(result.newMessages).toBeDefined()
   })
 
+  test('returns error when deferred tool has not been discovered via SearchExtraTools', async () => {
+    const mockTarget = makeMockTool('UndiscoveredTool', 'result')
+    const ctx = makeContext([mockTarget])
+
+    const result = await ExecuteTool.call(
+      { tool_name: 'UndiscoveredTool', params: {} },
+      ctx,
+      async () => ({ behavior: 'allow' }),
+      { type: 'assistant', content: [], uuid: 'msg1' } as never,
+      undefined,
+    )
+
+    expect(result.data).toEqual({
+      result: null,
+      tool_name: 'UndiscoveredTool',
+    })
+    expect(result.newMessages).toBeDefined()
+    expect(result.newMessages![0].content).toContain('has not been discovered')
+  })
+
   test('has correct name', () => {
     expect(ExecuteTool.name).toBe(EXECUTE_TOOL_NAME)
   })

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/ExitPlanModeTool/prompt.ts

@@ -20,10 +20,4 @@ Ensure your plan is complete and unambiguous:
 - Once your plan is finalized, use THIS tool to request approval
 
 **Important:** Do NOT use ${ASK_USER_QUESTION_TOOL_NAME} to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
-
-## Examples
-
-1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
-2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
-3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use ${ASK_USER_QUESTION_TOOL_NAME} first, then use exit plan mode tool after clarifying the approach.
 `

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/defines.ts

@@ -59,7 +59,7 @@ export const DEFAULT_BUILD_FEATURES = [
   'DAEMON', // 守护进程模式，长驻 supervisor 管理后台 worker（非 GB 级主因）
   'ACP', // ACP 代理协议，支持外部 agent 接入
   'WORKFLOW_SCRIPTS', // 工作流脚本（.claude/workflows/ 中的 YAML/MD）
-  'HISTORY_SNIP', // 历史消息裁剪，压缩上下文窗口
+  // 'HISTORY_SNIP', // 已禁用：snip 功能暂时关闭
   // 'CONTEXT_COLLAPSE', // 已禁用：实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理完全失效
   'MONITOR_TOOL', // Monitor 工具，流式监控后台进程输出
   // 'FORK_SUBAGENT',            // 已禁用：通过 Agent tool 的特殊方式实现了等效功能，无需再开

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/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/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/agents-platform/__tests__/AgentsPlatformView.test.tsx

@@ -1,127 +0,0 @@
-/**
- * Tests for AgentsPlatformView.tsx
- * Covers all 5 modes: list (empty), list (with agents), created, deleted, ran, error
- */
-import { describe, expect, mock, test } from 'bun:test';
-import * as React from 'react';
-import { renderToString } from '../../../utils/staticRender.js';
-
-// Mock cron utility before importing AgentsPlatformView
-mock.module('src/utils/cron.js', () => ({
-  cronToHuman: (expr: string) => `HumanCron(${expr})`,
-  parseCronExpression: () => null,
-  computeNextCronRun: () => null,
-}));
-
-const { AgentsPlatformView } = await import('../AgentsPlatformView.js');
-
-const sampleAgent = {
-  id: 'agt_abc123',
-  cron_expr: '0 9 * * 1',
-  prompt: 'Run standup report',
-  status: 'active' as const,
-  timezone: 'UTC',
-  next_run: '2026-05-05T09:00:00.000Z',
-};
-
-describe('AgentsPlatformView list mode', () => {
-  test('empty list shows placeholder message', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[]} />);
-    expect(out).toContain('No scheduled agents');
-  });
-
-  test('non-empty list shows agent count', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[sampleAgent]} />);
-    expect(out).toContain('Scheduled Agents (1)');
-  });
-
-  test('non-empty list shows agent id', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[sampleAgent]} />);
-    expect(out).toContain('agt_abc123');
-  });
-
-  test('non-empty list shows agent status', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[sampleAgent]} />);
-    expect(out).toContain('active');
-  });
-
-  test('non-empty list shows human-readable schedule', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[sampleAgent]} />);
-    expect(out).toContain('HumanCron(0 9 * * 1)');
-  });
-
-  test('list shows agent prompt', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[sampleAgent]} />);
-    expect(out).toContain('Run standup report');
-  });
-
-  test('list shows next run date', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[sampleAgent]} />);
-    // next_run is formatted via toLocaleString — just check it's rendered
-    expect(out).toContain('Next run');
-  });
-
-  test('list with null next_run shows em dash', async () => {
-    const agentNoNextRun = { ...sampleAgent, next_run: null };
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[agentNoNextRun]} />);
-    expect(out).toContain('—');
-  });
-
-  test('multiple agents rendered', async () => {
-    const agent2 = { ...sampleAgent, id: 'agt_xyz', cron_expr: '0 10 * * 2' };
-    const out = await renderToString(<AgentsPlatformView mode="list" agents={[sampleAgent, agent2]} />);
-    expect(out).toContain('Scheduled Agents (2)');
-    expect(out).toContain('agt_abc123');
-    expect(out).toContain('agt_xyz');
-  });
-});
-
-describe('AgentsPlatformView created mode', () => {
-  test('shows Agent created', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="created" agent={sampleAgent} />);
-    expect(out).toContain('Agent created');
-  });
-
-  test('shows agent id', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="created" agent={sampleAgent} />);
-    expect(out).toContain('agt_abc123');
-  });
-
-  test('shows schedule', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="created" agent={sampleAgent} />);
-    expect(out).toContain('HumanCron(0 9 * * 1)');
-  });
-
-  test('shows prompt', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="created" agent={sampleAgent} />);
-    expect(out).toContain('Run standup report');
-  });
-});
-
-describe('AgentsPlatformView deleted mode', () => {
-  test('shows deleted confirmation with id', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="deleted" id="agt_abc123" />);
-    expect(out).toContain('agt_abc123');
-    expect(out).toContain('deleted');
-  });
-});
-
-describe('AgentsPlatformView ran mode', () => {
-  test('shows triggered with agent id', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="ran" id="agt_abc123" runId="run_xyz" />);
-    expect(out).toContain('agt_abc123');
-    expect(out).toContain('triggered');
-  });
-
-  test('shows run id', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="ran" id="agt_abc123" runId="run_xyz" />);
-    expect(out).toContain('run_xyz');
-  });
-});
-
-describe('AgentsPlatformView error mode', () => {
-  test('shows error message', async () => {
-    const out = await renderToString(<AgentsPlatformView mode="error" message="Network failure" />);
-    expect(out).toContain('Network failure');
-  });
-});

src/commands/agents-platform/__tests__/launchAgentsPlatform.test.ts

@@ -1,6 +1,24 @@
-import { beforeAll, beforeEach, describe, expect, mock, test } from 'bun:test'
+/**
+ * Tests for launchAgentsPlatform.tsx
+ *
+ * Strategy per feedback_mock_dependency_not_subject:
+ * - DO NOT mock agentsApi.ts itself (would pollute api.test.ts)
+ * - Mock axios (the underlying HTTP layer) to control API responses
+ * - Let real agentsApi functions run real code paths
+ */
+
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from 'bun:test'
 import { debugMock } from '../../../../tests/mocks/debug.js'
 import { logMock } from '../../../../tests/mocks/log.js'
+import { setupAxiosMock } from '../../../../tests/mocks/axios.js'
 
 mock.module('src/utils/log.ts', logMock)
 mock.module('src/utils/debug.ts', debugMock)
@@ -9,42 +27,40 @@ mock.module('bun:bundle', () => ({
 }))
 
 // ── Analytics mock ──────────────────────────────────────────────────────────
+const realAnalytics = await import('src/services/analytics/index.js')
 const logEventMock = mock(() => {})
 mock.module('src/services/analytics/index.js', () => ({
+  ...realAnalytics,
   logEvent: logEventMock,
-  logEventAsync: mock(() => Promise.resolve()),
-  _resetForTesting: mock(() => {}),
-  attachAnalyticsSink: mock(() => {}),
-  stripProtoFields: mock((v: unknown) => v),
 }))
 
-// ── agentsApi mock ──────────────────────────────────────────────────────────
-const listMock = mock(async () => [
-  {
-    id: 'agt_1',
-    cron_expr: '0 9 * * 1',
-    prompt: 'hello world',
-    status: 'active',
-    timezone: 'UTC',
-    next_run: null,
-  },
-])
-const createMock = mock(async (cron: string, prompt: string) => ({
-  id: 'agt_new',
-  cron_expr: cron,
-  prompt,
-  status: 'active',
-  timezone: 'UTC',
-  next_run: null,
+// ── Auth / OAuth mocks ──────────────────────────────────────────────────────
+const realAuth = await import('src/utils/auth.js')
+mock.module('src/utils/auth.js', () => ({
+  ...realAuth,
+  getClaudeAIOAuthTokens: () => ({ accessToken: 'test-token-ap' }),
 }))
-const deleteMock = mock(async () => undefined)
-const runMock = mock(async () => ({ run_id: 'run_123' }))
-
-mock.module('src/commands/agents-platform/agentsApi.js', () => ({
-  listAgents: listMock,
-  createAgent: createMock,
-  deleteAgent: deleteMock,
-  runAgent: runMock,
+mock.module('src/services/oauth/client.js', () => ({
+  getOrganizationUUID: async () => 'org-uuid-ap',
+}))
+mock.module('src/constants/oauth.js', () => ({
+  getOauthConfig: () => ({ BASE_API_URL: 'https://api.anthropic.com' }),
+}))
+const realTeleportApi = await import('src/utils/teleport/api.js')
+mock.module('src/utils/teleport/api.js', () => ({
+  ...realTeleportApi,
+  getOAuthHeaders: (token: string) => ({ Authorization: `Bearer ${token}` }),
+  prepareWorkspaceApiRequest: async () => ({
+    apiKey: 'test-workspace-key-ap',
+  }),
+  prepareApiRequest: async () => ({
+    apiKey: 'test-api-key-ap',
+  }),
+}))
+mock.module('src/services/auth/hostGuard.ts', () => ({
+  assertSubscriptionBaseUrl: () => {},
+  assertWorkspaceHost: () => {},
+  assertNoAnthropicEnvForOpenAI: () => {},
 }))
 
 // ── cron mock ───────────────────────────────────────────────────────────────
@@ -57,19 +73,42 @@ mock.module('src/utils/cron.js', () => ({
   computeNextCronRun: () => null,
 }))
 
+// ── Axios mock ──────────────────────────────────────────────────────────────
+const axiosGetMock = mock(async () => ({}))
+const axiosPostMock = mock(async () => ({}))
+const axiosDeleteMock = mock(async () => ({}))
+const axiosIsAxiosError = mock((err: unknown) => {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    'isAxiosError' in err &&
+    (err as { isAxiosError: boolean }).isAxiosError === true
+  )
+})
+
+const axiosHandle = setupAxiosMock()
+axiosHandle.stubs.get = axiosGetMock
+axiosHandle.stubs.post = axiosPostMock
+axiosHandle.stubs.delete = axiosDeleteMock
+axiosHandle.stubs.isAxiosError = axiosIsAxiosError
+
 let callAgentsPlatform: typeof import('../launchAgentsPlatform.js').callAgentsPlatform
 
 beforeAll(async () => {
+  axiosHandle.useStubs = true
   const mod = await import('../launchAgentsPlatform.js')
   callAgentsPlatform = mod.callAgentsPlatform
 })
 
+afterAll(() => {
+  axiosHandle.useStubs = false
+})
+
 beforeEach(() => {
   logEventMock.mockClear()
-  listMock.mockClear()
-  createMock.mockClear()
-  deleteMock.mockClear()
-  runMock.mockClear()
+  axiosGetMock.mockClear()
+  axiosPostMock.mockClear()
+  axiosDeleteMock.mockClear()
 })
 
 function makeContext() {
@@ -79,8 +118,23 @@ function makeContext() {
 describe('callAgentsPlatform', () => {
   test('list (empty args) calls listAgents and returns element', async () => {
     const onDone = mock(() => {})
+    axiosGetMock.mockResolvedValueOnce({
+      data: {
+        data: [
+          {
+            id: 'agt_1',
+            cron_expr: '0 9 * * 1',
+            prompt: 'hello world',
+            status: 'active',
+            timezone: 'UTC',
+            next_run: null,
+          },
+        ],
+      },
+      status: 200,
+    })
     const result = await callAgentsPlatform(onDone, makeContext(), '')
-    expect(listMock).toHaveBeenCalledTimes(1)
+    expect(axiosGetMock).toHaveBeenCalledTimes(1)
     expect(onDone).toHaveBeenCalledTimes(1)
     expect(result).not.toBeNull()
     expect(logEventMock).toHaveBeenCalledWith(
@@ -91,21 +145,43 @@ describe('callAgentsPlatform', () => {
 
   test('list sub-command calls listAgents', async () => {
     const onDone = mock(() => {})
+    axiosGetMock.mockResolvedValueOnce({
+      data: { data: [] },
+      status: 200,
+    })
     await callAgentsPlatform(onDone, makeContext(), 'list')
-    expect(listMock).toHaveBeenCalledTimes(1)
+    expect(axiosGetMock).toHaveBeenCalledTimes(1)
   })
 
   test('create with valid cron calls createAgent', async () => {
     const onDone = mock(() => {})
+    axiosPostMock.mockResolvedValueOnce({
+      data: {
+        id: 'agt_new',
+        cron_expr: '0 9 * * 1',
+        prompt: 'Run standup',
+        status: 'active',
+        timezone: 'UTC',
+        next_run: null,
+      },
+      status: 201,
+    })
     const result = await callAgentsPlatform(
       onDone,
       makeContext(),
       'create 0 9 * * 1 Run standup',
     )
-    expect(createMock).toHaveBeenCalledTimes(1)
-    const [cron, prompt] = createMock.mock.calls[0] as [string, string]
-    expect(cron).toBe('0 9 * * 1')
-    expect(prompt).toBe('Run standup')
+    expect(axiosPostMock).toHaveBeenCalledTimes(1)
+    const callArgs = axiosPostMock.mock.calls[0] as unknown as [
+      string,
+      unknown,
+      unknown,
+    ]
+    const url = callArgs[0]
+    const body = callArgs[1] as Record<string, unknown>
+    expect(url).toContain('/v1/agents')
+    expect(body.cron_expr).toBe('0 9 * * 1')
+    expect(body.prompt).toBe('Run standup')
     expect(result).not.toBeNull()
     expect(logEventMock).toHaveBeenCalledWith(
       'tengu_agents_platform_create',
@@ -122,7 +198,7 @@ describe('callAgentsPlatform', () => {
       'create INVALID INVALID * * * my prompt',
     )
     // cron = 'INVALID INVALID * * *', mock returns null → no API call
-    expect(createMock).not.toHaveBeenCalled()
+    expect(axiosPostMock).not.toHaveBeenCalled()
     expect(logEventMock).toHaveBeenCalledWith(
       'tengu_agents_platform_failed',
       expect.anything(),
@@ -131,12 +207,18 @@ describe('callAgentsPlatform', () => {
 
   test('delete with id calls deleteAgent', async () => {
     const onDone = mock(() => {})
+    axiosDeleteMock.mockResolvedValueOnce({ data: {}, status: 204 })
     const result = await callAgentsPlatform(
       onDone,
       makeContext(),
       'delete agt_abc',
     )
-    expect(deleteMock).toHaveBeenCalledWith('agt_abc')
+    expect(axiosDeleteMock).toHaveBeenCalledTimes(1)
+    const callArgs = axiosDeleteMock.mock.calls[0] as unknown as [
+      string,
+      unknown,
+    ]
+    expect(callArgs[0]).toContain('agt_abc')
     expect(result).not.toBeNull()
     expect(logEventMock).toHaveBeenCalledWith(
       'tengu_agents_platform_delete',
@@ -146,12 +228,23 @@ describe('callAgentsPlatform', () => {
 
   test('run with id calls runAgent', async () => {
     const onDone = mock(() => {})
+    axiosPostMock.mockResolvedValueOnce({
+      data: { run_id: 'run_123' },
+      status: 200,
+    })
     const result = await callAgentsPlatform(
       onDone,
       makeContext(),
       'run agt_xyz',
     )
-    expect(runMock).toHaveBeenCalledWith('agt_xyz')
+    expect(axiosPostMock).toHaveBeenCalledTimes(1)
+    const callArgs = axiosPostMock.mock.calls[0] as unknown as [
+      string,
+      unknown,
+      unknown,
+    ]
+    expect(callArgs[0]).toContain('agt_xyz')
+    expect(callArgs[0]).toContain('/run')
     expect(result).not.toBeNull()
     expect(logEventMock).toHaveBeenCalledWith(
       'tengu_agents_platform_run',
@@ -167,11 +260,11 @@ describe('callAgentsPlatform', () => {
       'tengu_agents_platform_failed',
       expect.anything(),
     )
-    expect(listMock).not.toHaveBeenCalled()
+    expect(axiosGetMock).not.toHaveBeenCalled()
   })
 
   test('listAgents API error → error view returned', async () => {
-    listMock.mockRejectedValueOnce(new Error('network error'))
+    axiosGetMock.mockRejectedValueOnce(new Error('network error'))
     const onDone = mock(() => {})
     const result = await callAgentsPlatform(onDone, makeContext(), 'list')
     expect(result).not.toBeNull()
@@ -183,6 +276,10 @@ describe('callAgentsPlatform', () => {
 
   test('started event fires on every call', async () => {
     const onDone = mock(() => {})
+    axiosGetMock.mockResolvedValueOnce({
+      data: { data: [] },
+      status: 200,
+    })
     await callAgentsPlatform(onDone, makeContext(), '')
     expect(logEventMock).toHaveBeenCalledWith(
       'tengu_agents_platform_started',
@@ -190,10 +287,10 @@ describe('callAgentsPlatform', () => {
     )
   })
 
-  // ── Error-path branches (lines 77-86, 100-109, 128-136) ──────────────────
+  // ── Error-path branches ──────────────────────────────────────────────────
 
   test('createAgent API error → error view returned', async () => {
-    createMock.mockRejectedValueOnce(new Error('subscription required'))
+    axiosPostMock.mockRejectedValueOnce(new Error('subscription required'))
     const onDone = mock(() => {})
     const result = await callAgentsPlatform(
       onDone,
@@ -212,7 +309,7 @@ describe('callAgentsPlatform', () => {
   })
 
   test('deleteAgent API error → error view returned', async () => {
-    deleteMock.mockRejectedValueOnce(new Error('not found'))
+    axiosDeleteMock.mockRejectedValueOnce(new Error('not found'))
     const onDone = mock(() => {})
     const result = await callAgentsPlatform(
       onDone,
@@ -231,7 +328,7 @@ describe('callAgentsPlatform', () => {
   })
 
   test('runAgent API error → error view returned', async () => {
-    runMock.mockRejectedValueOnce(new Error('run failed'))
+    axiosPostMock.mockRejectedValueOnce(new Error('run failed'))
     const onDone = mock(() => {})
     const result = await callAgentsPlatform(
       onDone,
@@ -253,7 +350,7 @@ describe('callAgentsPlatform', () => {
     const onDone = mock(() => {})
     // Only 4 cron fields — parseArgs returns invalid
     await callAgentsPlatform(onDone, makeContext(), 'create 0 9 * *')
-    expect(createMock).not.toHaveBeenCalled()
+    expect(axiosPostMock).not.toHaveBeenCalled()
     expect(logEventMock).toHaveBeenCalledWith(
       'tengu_agents_platform_failed',
       expect.anything(),

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')
-  })
-})