background agent session 未与交互 session 区分 — 用户视角"仍在运行"歧义

[NorveraFlorent]

背景

Claude Code v2.1.139+ 引入 claude agents / /bg 后，session 多了 "bg fleet routine" 这一类。更隐蔽的是：用户即使从未主动跑 /bg，daemon 也会 auto-adopt 历史遗留的 bg session——每次 daemon self-restart（包括 CC 自更新触发的）都会 bg adopt: adopted=N dead=0，把 ~/.claude/sessions/ 里残留的 PID 文件对应的 session 重新拉回 fleet 继续 routine。

Launcher 当前活跃判定（SessionScanner.swift::scanActiveSessions 读 sessions JSON → kill(pid, 0)）逻辑没错，但判定的语义在 bg fleet 引入后变多义：绿点既可能是"用户在前台 attach 的 session"，也可能是"daemon 在跑 routine"。而 sessions JSON 本身没有 sentinel 字段区分（实测 fleet routine 跑时的 kind 仍是 "interactive"，和前台 session 一样）。

用户视角的故事

1. 用户关闭了所有 Claude Code UI
2. 看到 launcher 菜单栏某个 session 仍间歇性显示绿点
3. 点击 → claude --resume <id> 失败：Session is currently running as a background agent (bg). Use 'claude agents' to find and attach to it
4. 用户 kill <pid> → 绿点消失 → 一段时间后 daemon 重新 claim-spare → 又显示绿点
5. 真正彻底关掉得跑 claude agents kill <id> —— 但用户不会知道，因为 launcher 不暴露这个维度

这件事独立成立——不依赖任何 daemon 异常或偶发现象。只要 bg fleet 机制存在 + launcher 不读这一维，gap 就在那儿。

已自己机器实证否定的一个方向

我原本以为 ~/.claude/sessions/<pid>.json 在 fleet routine 跑时会写不同的 kind（比如 "background"），launcher 读这个 sentinel 就够了。实测否定：本机 PID 39482 那个 session（daemon.log 显示被反复 bg claimed-spare 732225a2 (fleet) 唤起）写出来的 kind 仍是 "interactive"。这条 zero-cost 的路目前走不通。

几个可能方向（作者决定，不走 PR）

按"破坏 launcher 设计原则的程度"从小到大：

1. 如果作者愿意往这个方向走：claude agents list 是官方 CLI 接口，符合 launcher "只在 CC 官方 CLI 和文件接口上做 UI 层"的原则。launcher 调它来给 fleet session 标 "BG" / "🤖 routine" 角标（纯 enrichment、零交互改变）
2. 右键菜单加一项 "Kill background agent..."（背后 spawn claude agents kill <id>）
3. 顶级菜单加 "Background Agents (n)" 子组，展开 fleet——这是 1+2 的菜单结构化版本

关于不走 PR

尊重 launcher README 里"只在 Claude Code 官方 CLI 和文件接口上做 UI 层。不修改 Claude Code 的源代码、不改动会话 JSONL、不接触 Claude Code 内部状态"的设计精神。方向选哪个、要不要做都由作者裁决。这个 issue 只把现象和痛点摆清楚。

环境

• Claude Code: 2.1.143
• forge-launcher: 当前 main（本地装 v0.1.1 后再升）
• macOS 26 / Darwin 25.5.0

[LinekForge]

感谢这个非常详细的分析，把现象、根因和方向都梳理得很清楚。

我们做了调研：当前 CC 2.1.143 的 session JSON 里，bg session 的 kind 字段仍然写的是 "interactive"（和你观察到的一致），claude agents 在非 TTY 环境下也不可用。也就是说目前没有可靠的 sentinel 来区分前台和后台 session。

从 CC 二进制逆向看，kind 的合法值确实包含 "bg" / "daemon" / "daemon-worker"——只是当前版本似乎还没有正确写入。一旦上游修复了这个问题，launcher 加 kind 字段读取 + 角标/分组就是很自然的事。

先保持 open，等 CC 更新后回来看。如果你那边观察到新版本开始正确写入 kind: "bg"，非常欢迎回来更新一下，我们会很快跟进。

—— Forge

[LinekForge]

补充一下调研结果，有个好消息：

bg session 的状态文件在 ~/.claude/jobs/<id>/ 目录下（state.json），和 interactive session 的 ~/.claude/sessions/ 是分开的。这意味着 launcher 可以通过检查 ~/.claude/jobs/ 有没有对应 sessionId 的目录来区分，不需要依赖 kind 字段。

另外 CC 已经有了独立的管理命令：claude attach <id>、claude stop <id>、claude logs <id> 等，launcher 后续可以接入。

目前 bg agent 还在快速迭代（Windows 还被 feature gate 关着，状态显示也有几个已知 bug），等稳定几个版本后我们会跟进实现。感谢你把这个维度完整地摆出来，到时候做起来会很顺。

—— Forge

[LinekForge]

更新一下调研结果（2026-05-19）：

CC 的 bg session 分类机制目前仍不稳定：

• v2.1.139 引入的 daemon 把所有 session 标成 template: "bg"（包括交互式），导致 worktree 隔离误触发（#59848）。v2.1.143 加了 worktree.bgIsolation: "none" 作为 workaround，但分类逻辑的根因未修
• /compact 在 bg 进程内会把 sessionKind: "bg" 写进 JSONL，导致 session 从 resume picker 消失（#59415）。v2.1.144 修了 /resume 支持显示 bg session
• fleet deleteJob 静默删除主 session JSONL（#60368），约 25% session 变孤儿。仍 open
• agent view 不显示 fleet session（#60437），仍 open

~/.claude/sessions/*.json 里的 kind 字段仍然不可靠（全部是 "interactive"）。~/.claude/jobs/ 目录检测理论上可行，但 fleet 生命周期 bug 会删 JSONL，整个 bg 生态不稳定。

结论不变：等 CC 的 bg session 机制稳定后再跟进。目前跟进反而会踩坑。

—— Forge