宜博 / lemonboss

起因是「全量测试偶发挂一条」。查下来既不是回归、也不是那 45 个孤儿进程（它们 CPU 早归零、
不再写任何东西），而是**还活着的心跳在测试扫描 system/agents/ 的同时往里建目录**：

    locator.taskDir() 的落点是 system/agents/<agent>/<companyId>/<taskId>，
    运行态目录落在本体目录里属既定设计；但心跳每 5 分钟建一个新的
    （cto/_global/ 已 263 个子项且在涨），于是扫描 system/agents/ 的守卫测试
    （no-dead-path-references 那一类）会撞上瞬时竞态：列到了目录名，进去时那一层还没写完。

症状是偶发假失败、重跑就好 —— 这类最费人，因为第一反应总是去怀疑自己刚改的代码。

改法：server/index.js 启动的那个 setTimeout 块里，恰好装着全部「会自己起 agent 的东西」
（两处中断恢复 + 任务队列扫描 + 两路心跳），所以一条早退就够，不必在五个地方各加一个判断。

    DISABLE_BACKGROUND_AGENTS=1 bash start.sh

实测：127 文件 / 1226 用例全绿，跑前跑后 cto/_global 子项数都是 263。

**验证它生效不能只看日志里的 ⏸** —— 那只证明代码走到了早退。硬判据是目录数前后相等，
也就是真的没有东西在写。文档 §七 把这条写成了可粘的三行。

排掉的两个坑，都记在文档和 .env.example 里：

1. `.env` 里不能给这个键赋空值。start.sh 是 `set -a; source .env` 加载的，.env 里只要
   存在同名键（哪怕空的）就会盖掉命令行传进来的 =1，而且不报错。所以 .env.example 里
   它只以注释形式出现 —— 一个「示例文件顺手写全」的习惯会直接让开关失效。

2. 开关生效后 `[TaskQueue] 🚀 已启动` 仍会打印，那是另一个模块：services/task-queue.js
   （ArenaSK 时代 /api/claude-chat 的队列，routes/claude-chat.js 模块加载时起），
   和批 3 的 services/task-scheduler.js 同名不同物。它的心跳只扫内存里的 this.tasks，
   不碰 system/agents/，不是干扰源。名字撞车，容易误判成开关没生效。

文档同步：
  - docs/done/claude-cli-session-leak.md §七 重写（原文写的是「得让测试隔离，或跑前停心跳」，
    现在后者已实现，改成开关的用法 + 硬判据 + 上面两个坑）；原第 2 条降为 §七之二
  - CLAUDE.md 测试命令块加一行（这是找「怎么跑测试」的人真正会看的地方）
  - docs/README.md 索引行补上开关

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

泄漏被修过一次（310a2b2 / 3e718aa），修完照样漏。第二次排查发现原因不是修错了，而是：

    系统里有两个互相独立的会话池，上一次只修了其中一个；而被修的那个，还漏了一条分支。

    池 A  routes/agent-chat.js 的 sessions       ← /api/agent/:id/chat，含两路心跳
    池 B  src/core/session-pool.js 的 SessionPool ← AgentManager.callAgent，图执行 / DevLoop

两者没有任何共享代码，回收逻辑各写各的。这个结构性事实此前没有任何一处记着，
所以第二个人查到同一个症状时会重走一遍全程 —— 这份文档就是为了让第三个人不必再走。

正文八节，除了两个洞各自的成因与修法（b0b2b62 / 2092a2e），有三处是排查方法而非结论：

§三 按 cwd 第三层判断孤儿归属的对照表。两个池子都把 cwd 下沉到运行态目录，
     `_global` / `_no-task` 是 agent-locator 的保留缺省值、两边都会出现，不能靠它区分。

§四 为什么上一版守卫是瞎的。dropSession 和 closeSession 都会让会话从池子里消失，
     黑盒探针两种情况都返回 false —— 差别只在子进程死没死，而那是探针看不见的维度。
     选探针要问的不是「能不能测出正确行为」，而是「能不能区分正确行为和这个具体的错误行为」。

§八 三步定位脚本，外加一条：先确认跑着的服务器进程是什么时候启动的，再去看代码。
     本次排查中，正在跑的实例比修复 commit 早 18 秒启动，代码里有的修复它并没有。

线上验证（PID 63099，13 分钟窗口两轮心跳）：触发 5 / 完成 5 / 回收 5，峰值子进程 3、稳态 0。
17:13:32 那个 3 正是泄漏时代的签名（cto+coo+qa-judge 同秒触发），清理前那批孤儿一个都不回收，
现在 30 秒内全部释放。窗口内没有失败心跳，所以 2092a2e 那条 catch 路径是靠单测的变异检验
保证的、不是靠线上观察 —— 文档 §六 里写明了，没算成已验证。

docs/README.md 同步加索引条目（no-dead-path-references 守卫 4 条全绿）。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>