PTY 和进程监督计划

1. 问题和目标

我们需要一个可靠的统一生命周期来管理各种长期运行的命令执行：

• exec 前台运行
• exec 后台运行
• process 后续操作（poll、log、send-keys、paste、submit、kill、remove）
• CLI agent runner 子进程

目标不只是支持 PTY。目标是可预测的所有权、取消、超时和清理，没有不安全的进程匹配启发式。

2. 范围和边界

• 实现保持在 src/process/supervisor 内部。
• 不为此创建新包。
• 在实际可行处保持当前行为兼容性。
• 不扩展范围到终端回放或 tmux 风格的会话持久化。

3. 本分支已实现

监督器基线已就位

• 监督器模块位于 src/process/supervisor/*。
• Exec 运行时和 CLI runner 已经通过监督器 spawn 和 wait 路由。
• 注册表 finalization 是幂等的。

本轮已完成

1. 显式 PTY 命令契约 — SpawnInput 现在是 src/process/supervisor/types.ts 中的区分联合体。PTY 运行需要 ptyCommand 而非复用通用 argv。

2. 进程层类型解耦 — 监督器类型不再从 agents 导入 SessionStdin。进程本地 stdin 契约在 src/process/supervisor/types.ts 中（ManagedRunStdin）。

3. 进程工具生命周期所有权改进 — process kill/remove 现在先通过监督器请求取消，当监督器查找未命中时使用进程树回退终止。

4. 单一来源看门狗默认值 — 添加了 src/agents/cli-watchdog-defaults.ts 中的共享默认值。

5. 死代码清理 — 从 src/agents/bash-tools.shared.ts 移除了未使用的 killSession 辅助路径。

6. 直接监督器路径测试 — 添加了 src/agents/bash-tools.process.supervisor.test.ts。

7. 可靠性缺口修复 — 监督器查找未命中时回退到真正的 OS 级进程终止；子进程 adapter 使用进程树终止语义。

8. PTY 契约边缘情况覆盖 — 添加了逐字 PTY 命令转发和空命令拒绝的测试。

4. 剩余缺口和决策

可靠性状态

两个必需的可靠性缺口现已闭合，回归测试已添加。

持久性和启动协调

重启行为现在显式定义为仅内存生命周期。reconcileOrphans() 按设计保持为空操作。活跃运行在进程重启后不恢复。这是本次实现轮次的有意边界，以避免部分持久化风险。

可维护性后续

runExecProcess（src/agents/bash-tools.exec-runtime.ts）仍处理多个职责，可在后续拆分为聚焦的辅助函数。

5. 实现计划

必需的可靠性和契约项的实现轮次已完成。可选后续：拆分 runExecProcess 为聚焦辅助，不产生行为漂移。

6. 文件映射

进程监督器

• src/process/supervisor/types.ts — 区分 spawn 输入和进程本地 stdin 契约
• src/process/supervisor/supervisor.ts — 使用显式 ptyCommand
• src/process/supervisor/adapters/child.ts 和 pty.ts — 从 agent 类型解耦
• src/process/supervisor/registry.ts — 幂等 finalize 保留

Exec 和 process 集成

• src/agents/bash-tools.exec-runtime.ts — 显式传递 PTY 命令
• src/agents/bash-tools.process.ts — 通过监督器取消并带真实进程树回退

CLI 可靠性

• src/agents/cli-watchdog-defaults.ts — 共享基线
• src/agents/cli-backends.ts 和 src/agents/cli-runner/reliability.ts — 消费相同默认值

7. 本轮验证运行

单元测试和端到端测试列表参见英文原文。构建验证使用 pnpm build（和 pnpm check 做完整 lint/docs 门控）。

8. 保持的运维保证

• Exec 环境加固行为不变。
• 审批和白名单流程不变。
• 输出脱敏和输出上限不变。
• PTY adapter 仍保证在强制 kill 时等待结算和监听器释放。

9. 完成定义

1. 监督器是托管运行的生命周期所有者。
2. PTY spawn 使用显式命令契约，无 argv 重构。
3. 进程层对监督器 stdin 契约不依赖 agent 层类型。
4. 看门狗默认值单一来源。
5. 定向的单元和端到端测试保持绿色。
6. 重启持久性边界已显式记录或完全实现。

10. 总结

本分支现在拥有连贯且更安全的监督形状：显式 PTY 契约、更清晰的进程分层、监督器驱动的取消路径、真实的回退终止、进程树取消、统一的看门狗默认值、显式的仅内存重启边界。