forge-engine: multi-instance duplicate triggers from per-session engine-channel

[AmberCXX]

问题描述

当多个 Claude Code session 同时运行时，每个 session 都启动独立的 engine-channel MCP 子进程。所有 engine-channel 实例各自注册定时器并独立触发任务，导致：

症状

1. 任务重复触发：同一任务被 N 个 engine-channel 实例同时触发。实测 22:59 的睡觉提醒在同一天被触发了 4 次（对应 4 个在线实例）。
2. 调度状态抖动：修改 engine.d/ 下任一配置文件时，N 个 engine-channel 各自执行 partial reload，trigger-log 中同一条 部分重排 日志出现 N×M 次（M 为文件 watcher 触发次数）。
3. session 死亡 = 定时器丢失：forge-engine: missed task recovery on session restart + busy-session task drop #19 已加了错过任务的通知补救，但如果所有 session 都死了（比如夜间），定时器全丢，直到有人重开 session。

复现

# Terminal 1: 启动一个 CC session（engine-channel 自动启动）
# Terminal 2: 启动另一个 CC session（又一个 engine-channel）
# 等下一个整点任务触发 → 收到 2 条相同通知

当前环境有 3 个 CC session 运行中：

s000 → engine-channel PID 54699
s001 → engine-channel PID 69013  
s002 → engine-channel PID 74905

engine trigger log 证据（22:59 任务触发 4 次）：

## 2026-05-11 22:59 — heartbeat
- 来源: task_hourly_checkin.json
- 内容: 🌙 睡觉提醒 ...
## 2026-05-11 22:59 — heartbeat  ← 重复
## 2026-05-11 22:59 — heartbeat  ← 重复
## 2026-05-11 22:59 — heartbeat  ← 重复

根因

engine-channel.ts 是 CC MCP server 子进程，生命周期绑定 CC session。多个 session = 多个独立调度器 = 无协调、无去重。

当前架构：

Hub daemon (stable, one instance)
  ├── engine-channel (session 1) → timers + fire
  ├── engine-channel (session 2) → timers + fire  ← 重复
  └── engine-channel (session 3) → timers + fire  ← 重复

建议方案

把 scheduler 从 engine-channel 移到 Hub daemon，Hub 内部维护单一调度器实例：

Hub daemon (stable, one instance)
  ├── engine-scheduler (built into Hub) → one set of timers → fire exactly once
  │   └── notifies connected CC sessions via MCP
  ├── CC session 1 (receives task notifications)
  └── CC session 2 (receives task notifications, can serve as fallback executor)

要点：

• 调度器是 Hub daemon 的一部分（和 message routing 同级），不再依赖 CC session 生命周期
• 任务触发时 Hub 通过 MCP notification 通知在线 session
• 多 session 时由 primary instance 执行（或由 Hub 做简单的 instance affinity），避免重复
• engine-channel 可简化为纯桥接层（接收 Hub 事件 → 转发给 CC），不再管理定时器

临时 workaround

用户侧：只保留 1 个 CC session，关掉多余的 terminal。但这与多任务并行工作流冲突。

---

环境：macOS 14.6.1 · Bun 1.3.13 · forge-hub v0.2.0

forge-hub doctor 输出：

✓ Bun installed
✓ Hub server runtime
✓ Hub client runtime
✓ LaunchAgent plist
✓ MCP registered
✓ ffmpeg available
✓ lark-cli available
✓ approval_channels configured: [feishu, wechat]
✓ Hub server running (v0.2.0, uptime 1964min)
✅ All checks passed

[LinekForge]

感谢详细的复现和分析，trigger log 的证据很清楚。

根因确认

和你的判断一致：engine-channel 是 per-session 的 MCP 子进程，多 session = 多独立调度器 = 无协调。这是 engine 作为实验模块时没有考虑多实例场景的设计遗留。

我们的方向

你提的"scheduler 搬进 Hub daemon"是一个可行方向，但我们想走一个更灵活的路径——任务亲和性（task affinity），而不只是去重。

核心思路：每个任务可以指定由哪个实例负责执行，其他实例不管。

具体设计

1. 任务配置加 assignee 字段

{
  "schedules": [
    {
      "hour": 22, "minute": 59,
      "template": "[提醒] 🌙 睡觉提醒",
      "sender": "heartbeat",
      "assignee": "@chat"
    }
  ]
}

assignee 对应 Hub 的 instance tag（就是 fh hub peers 里看到的 @chat、@ops 这些）。只有 tag 匹配的实例的 engine 会排定这个任务，其他实例跳过。

2. engine-channel 启动时从 Hub 获取身份

engine-channel 目前和 Hub 完全独立。改造后它会在启动时通过 Hub HTTP API 查询自己所属 CC session 的 tag，拿到之后按 tag 过滤任务。Hub 不介入调度逻辑——只提供"你是谁"这一个信息，engine 保持独立调度能力。

3. 没有 assignee 的任务的去重

没指定 assignee 的任务需要一个兜底规则，避免多实例重复触发。目前倾向于：默认归 primary instance（hub-config.json 里配的 primary_instance），或者要求所有任务必须写 assignee。具体方案还在讨论。

这个方向比"搬进 Hub"好在哪

• engine 保持模块独立性——不需要把 scheduler 代码搬进 hub-server，两者只有轻量协作
• 灵活分工——不同实例可以负责不同类型的任务（陪伴窗口管提醒，工作窗口管代码检查），不只是去重
• 渐进式——现有用户只开一个 session 的完全不受影响，多实例用户按需加 assignee

时间线

这个改动涉及 engine-channel、scheduler、Hub API、任务配置 schema 多处，不是一个 quick fix。近期会开始设计和实现，进展会更新在这个 issue 里。

临时 workaround 和你说的一样：只保留一个 CC session 负责 engine 任务。

---

— Forge