# §15 — Compact 检测方案修正

> 状态：✅ 已完成（gateway log + jsonl 配对）
> 作者：庞统
> 日期：2026-06-11（v4），2026-06-13（v5）
> 框架：基于 §07 Spawner Acquire-First
> 评审：仲达 4+2 轮评审
> 备选方案：B（内存 flag + sessions.json status），见 §2B

---

## 0. v5 方案（已实现）

### 0.1 方案概述

**gateway log 开始标记（precheck `route=compact_then_truncate`）+ jsonl 结束标记（`type: "compaction"` entry）配对**。

- **开始标记**：扫描 gateway 日志，找含目标 agent sessionKey 且 `route=compact_then_truncate` 的 precheck 日志行，提取时间戳。
- **结束标记**：扫描 session jsonl，找开始时间之后的 `type: "compaction"` entry。
- **判定逻辑**：有开始无结束 → compact 进行中 → skip ticker；有开始有结束 → compact 已完成 → 不 skip。
- **超时兜底**：开始标记超过 15 分钟仍未结束 → 自动忽略（防止死锁）。

### 0.2 三种 Compact 触发路径分析

Gateway 的 compact 有多种触发路径，日志表现不同：

| 触发路径 | 有开始标记？ | 有 sessionKey？ | 有 compaction 结束标记？ | 检测策略 |
|---------|------------|---------------|----------------------|--------|
| **overflow** | 有（`attempting auto-compaction`） | ❌ 不含 | 有 | 依赖 precheck 覆盖 |
| **timeout** | 有（`[timeout-compaction]` + `attempting`） | ❌ 推测不含 | 有 | 依赖 precheck 覆盖 |
| **precheck** | 有（`[context-overflow-precheck]` + `route=compact_then_truncate`） | ✅ 含 | 有 | **直接检测** |
| **threshold** | 无（静默执行） | — | 有 | counter+lock+status 保护 |
| **manual** | 无（静默执行） | — | 有 | counter+lock+status 保护 |

### 0.3 为什么只依赖 precheck 标记

1. **overflow/timeout 标记不含 sessionKey**：实测证实 overflow 标记（`context overflow detected; attempting auto-compaction for zhipu/glm-5.1`）不包含 `agent:xxx:main` 格式的 sessionKey，被前置 `session_key not in msg` 过滤跳过，是死代码。
2. **precheck 总在 overflow 之前触发**：同一 compact 事件中，precheck `route=compact_then_truncate` 先检测到，overflow 是 fallback。所以 precheck 已覆盖 overflow 场景。
3. **threshold/manual 无开始标记**：这两种是静默执行，没有 gateway 日志标记。它们依赖 counter+lock+status 三重保护（见 §07），不需要 gateway 日志检测。

> **注意**：`route=truncate_tool_results_only` 的 precheck 不触发 compact 检测，只有 `route=compact_then_truncate` 才触发。

### 0.4 超时兜底

15 分钟超时窗口：如果 compact 开始标记超过 15 分钟仍无结束标记，自动忽略该开始标记。这覆盖了：
- daemon 重启后残留的开始标记
- 极端长时间的 compact（正常 compact 通常 < 7 分钟）
- 日志轮转导致的结束标记丢失

---

## 1. 问题

### 1.1 现象

2026-06-11 14:02，pangtong main session 正在做 compaction（13:59:26 开始，14:06:00 结束，耗时 ~6.5 分钟），但 spawner Phase 2 检查时 `compact=False`，仍然 spawn 了新进程处理 Mail，导致两个 agent turn 撞车。

### 1.2 根因

当前 compact 检测方法 `_check_recent_compaction_jsonl` 扫描 session jsonl，查找 `type == "compaction"` 事件。这是 compact **完成后**才写入的摘要记录，compact **进行中**时不存在 → 漏检。

同时 Gateway 触发 compact 时先把 session 标为 `done`，所以 `status=running + lock_pid_alive` 检查也无效。14:02:11 实际状态：`status=done lock_pid_alive=False compact=False`——三个检查全部漏过。

## 2. 方案 A：Trajectory prompt.submitted 检测（v4，主选方案）

### 2.1 方案演进

| 版本 | 方案 | 问题 |
|------|------|------|
| v1 | trajectory jsonl 间接推断 | trajectoryPath 不可用，需多文件 |
| v2 | gateway precheck 开始标志 | 覆盖率仅 30%，post-compact retry 无开始标志 |
| v3 | rotation-only + 120s 窗口 | 120s 覆盖不了多轮 compact loop（实测 pangtong 13:59→14:50 共 5 轮 rotation，总耗时 ~51 分钟，PR #36 已合并但无法覆盖） |
| **v4** | **trajectory prompt.submitted** | **源码+数据双重验证，仲达背靠背确认** |

### 2.2 核心洞察

**源码证据**（`selection-But6hGR0.js` L14040-14085）：

```javascript
if (preemptiveCompaction?.shouldCompact) {
    skipPromptSubmission = true;  // ← compact 时跳过 prompt.submitted
}
if (!skipPromptSubmission) {
    trajectoryRecorder?.recordEvent("prompt.submitted", { ... });
}
```

当 context-overflow 触发 compact 时，Gateway 跳过 `prompt.submitted` 事件。
正常 turn 一定有 `prompt.submitted`。

**仲达背靠背验证**：`skipPromptSubmission` 有 7 条路径（不只 compact），但仲达指出：
**检测目标不是"是否在 compact"，而是"session 是否处于正常状态"。**
所有跳过 prompt.submitted 的场景（compact/timeout/hook block/session 结束）
都是不应该 spawn ticker 的状态，误判方向安全。

**实测数据**（仲达背靠背重新验证，2026-06-11）：
- pangtong 39 个 turn：34 有 prompt.submitted（正常），5 无
  - 4 个 tool loop 子迭代（compactionCount=0, <1s, gateway 无 compact 事件）
  - 1 个 context-overflow precheck 触发 compact
- simayi 24 个 turn：23 有，1 无（tool-result truncation succeeded）
- 合计 6/63 = ~9.5% 无 prompt.submitted，其中真正 compact 仅 1 例
- **所有无 prompt.submitted 的场景都是不应 spawn ticker 的状态**，方向安全

### 2.3 检测逻辑

```
1. 构造 trajectory jsonl 路径：{sessionFile}.trajectory.jsonl
2. 读文件尾部，按 session.started 分组找最后一个完整 turn
3. 如果该 turn 有 prompt.submitted → 正常 turn → 不 skip
4. 如果该 turn 有 prompt.skipped → 空白 prompt → 不 skip
5. 如果两者都无 → 非正常状态 → skip ticker
6. 超过 30min 没有新事件 → 兜底放行
```

**为什么不需要 gateway 日志？**
- trajectory jsonl 已经包含了完整的 turn 生命周期
- prompt.submitted 是 turn 级别的标志，不需要匹配开始/结束
- 不需要维护跨 tick 的内存状态

### 2.4 为什么不用 session jsonl 的 `type: "compaction"` 事件？

每轮 compact 结束，session jsonl 确实会写入 `type: "compaction"` 摘要事件。
但 compact 后 Gateway 会 rotate transcript（创建新 session file），
compaction 事件写在**旧 session jsonl** 里（变成 .reset 文件），
当前 main session 指向的 jsonl 中没有这些事件。

这就是现有 `_check_recent_compaction_jsonl` 检测不到的根本原因。

## 2B. 备选方案 B：内存 flag + sessions.json status

如果方案 A 在实际使用中不够，可补充方案 B。

```
1. gateway 日志发现 rotation 或 precheck → 设置内存 flag: compacting=True
2. 每个 ticker 检查：
   - flag=True + sessions.json status=running → 清 flag（compact 结束）
   - flag=True + 超过 30min → 清 flag（兜底放行）
   - flag=True → skip ticker
3. daemon 重启会丢失 flag（可接受，重启后状态已刷新）
```

**优点**：精确检测 compact 结束（status 恢复 running）
**缺点**：需要维护内存状态、依赖两个数据源、daemon 重启丢失状态
**触发条件**：仅在方案 A 实际运行中发现不足时实施

## 3. 改动范围（方案 A）

| 文件 | 改动 | 行数估计 |
|------|------|---------|
| `spawner.py` | 新增 `_check_compact_in_progress_trajectory()` | ~50 行 |
| `spawner.py` | `_check_session_state()` 调用新方法，替换旧方法 | ~5 行 |
| `tests/test_spawner_compact.py` | 更新单元测试 | ~30 行 |

**总计 ~85 行代码改动。**

## 4. 实现细节（方案 A）

### 4.1 核心方法

```python
def _check_compact_in_progress_trajectory(self, session_file: str, timeout_minutes: int = 30) -> bool:
    """检查 trajectory jsonl 尾部，判断 session 是否处于非正常状态。
    
    检测逻辑：最后一个完整 turn 没有 prompt.submitted → 非正常状态 → skip ticker。
    覆盖：compact、timeout、hook block、session 结束等所有非正常状态。
    """
    traj_path = f"{session_file}.trajectory.jsonl"
    if not os.path.exists(traj_path):
        return False
    
    # 读尾部 500KB
    with open(traj_path, 'rb') as f:
        f.seek(0, 2)
        size = f.tell()
        f.seek(max(0, size - 500 * 1024))
        tail_lines = f.readlines()
    
    # 按 session.started 分组，找最后一个完整 turn
    last_turn_events = []
    current_turn = []
    for raw_line in tail_lines:
        try:
            obj = json.loads(raw_line)
        except (json.JSONDecodeError, ValueError):
            continue
        
        event_type = obj.get("type", "")
        
        if event_type == "session.started":
            if current_turn:
                last_turn_events = current_turn
            current_turn = [obj]
        else:
            current_turn.append(obj)
    
    if current_turn:
        last_turn_events = current_turn
    
    if not last_turn_events:
        return False
    
    # 30min 兜底：最后一个事件超过 30min → 放行
    last_ts = None
    for evt in reversed(last_turn_events):
        ts = evt.get("ts") or evt.get("timestamp")
        if ts:
            last_ts = ts
            break
    
    if last_ts:
        try:
            from datetime import datetime, timezone
            # trajectory 时间是 ISO UTC
            if last_ts.endswith('Z'):
                last_dt = datetime.fromisoformat(last_ts.replace('Z', '+00:00'))
            else:
                last_dt = datetime.fromisoformat(last_ts)
            age = datetime.now(timezone.utc) - last_dt
            if age.total_seconds() > timeout_minutes * 60:
                return False  # 超时放行
        except (ValueError, TypeError):
            pass
    
    # 检查最后一个 turn 是否有 prompt.submitted
    has_prompt_submitted = any(
        evt.get("type") == "prompt.submitted" for evt in last_turn_events
    )
    has_prompt_skipped = any(
        evt.get("type") == "prompt.skipped" for evt in last_turn_events
    )
    
    if has_prompt_submitted or has_prompt_skipped:
        return False  # 正常 turn
    
    # 既无 submitted 也无 skipped → 非正常状态 → skip
    return True
```

### 4.2 Phase 2 集成

```python
# 在 _check_session_state 中替换旧方法
compact = self._check_compact_in_progress_trajectory(session_file)
if not compact:
    compact = self._check_recent_compaction_jsonl(...)  # fallback
    
if compact:
    blockers.append(("session_compacting", None))
```

### 4.3 trajectory 路径构造

trajectory jsonl 路径 = `{sessionFile}.trajectory.jsonl`，其中 sessionFile 来自 sessions.json。

实测验证：
- `~/.openclaw/agents/pangtong-fujunshi/sessions/745b35bb-...-e8e8988d.jsonl`
- → trajectory: `~/.openclaw/agents/pangtong-fujunshi/sessions/745b35bb-...-e8e8988d.trajectory.jsonl`

## 5. 边界情况

| 边界情况 | 处理 | 误判方向 |
|---------|------|----------|
| trajectory 不存在 | 返回 False（fallback） | 安全 |
| tool loop 子迭代 | 无 prompt.submitted → skip | 保守但安全（~8%） |
| timeout turn | 无 prompt.submitted → skip | 安全（timeout 也不该 spawn） |
| hook block | 无 prompt.submitted → skip | 安全 |
| truncation 成功 | 无 prompt.submitted → skip | 安全（后面会 retry） |
| session 结束空 turn | 无 prompt.submitted → skip | 安全 |
| 空白 prompt | 有 prompt.skipped → 不 skip | 正确区分 |
| 30min 无新事件 | 兜底放行 | 防死锁 |
| compact 后 transcript rotate | 读当前 sessionFile 对应的 trajectory | 路径正确 |
| budget compact | 有 prompt.submitted → 不 skip | 正确（budget compact 不阻止 spawn） |

## 6. 测试验证

### 6.1 单元测试（更新 test_spawner_compact.py）

- `_check_compact_in_progress_trajectory`：
  - 正常 turn（有 prompt.submitted）→ False
  - compact turn（无 prompt.submitted）→ True
  - 空白 prompt（有 prompt.skipped）→ False
  - 超过 30min 兜底 → False
  - trajectory 不存在 → False
  - 空 trajectory → False
  - 多 turn 尾部只看最后一个 → 正确

### 6.2 集成验证

- `pytest -m "not e2e"` 全量测试

## 7. 关联设计

- §07 Spawner Acquire-First（§4.5 O5 compact 扫描条件收紧）
- §08 Classify Outcome Optimization（compact_hanging 处理）

## 8. 实验验证（2026-06-13）

### 8.1 Manual Compact 实验

对 `jiangwei-infra` 执行 `/compact`，每秒采样 4 个维度，完整时间线：

| 时间 | 事件 | 维度 |
|---|---|---|
| 08:08:57 | 基线：lock=0, status=done, compact=2, jsonl=1942 | 全部 |
| 08:09:22 | **Lock file 出现** + JSONL +1 行 | lock, jsonl |
| 08:09:22~08:12:31 | Lock 持有中，status=done 不变 | lock |
| 08:12:32 | **Lock 释放** + compaction+1 + GW 2 条新日志 | 全部 |
| 08:12:32.035 | GW: `[compaction] rotated active transcript` | gateway log |
| 08:12:32.057 | GW: `⇄ res ✓ sessions.compact 191267ms` | gateway log |

**Compact 耗时**：191267ms ≈ 3 分 11 秒。

### 8.2 关键结论

1. **Lock file 是最通用的 compact 运行时标记**：manual compact 开始时立即出现，结束时释放，覆盖全程。
2. **Gateway log 无开始标记**：manual compact 不产生 `context-overflow-precheck` 或 `route=compact_then_truncate`，只有结束标记（`rotated active transcript` + `sessions.compact` WS 响应）。
3. **sessions.json status 不变**：全程 `done`，不出现 `compacting` 之类的中间状态。
4. **JSONL compaction entry 是可靠的结束标记**：所有路径（precheck/manual/threshold）完成后都会写入。
5. **V5 安全性**：manual/threshold 无开始标记 → V5 不会误判为进行中 → 不会在完成后误阻塞。Phase 2 的 `session_locked`（lock file 检查）覆盖了 compact 期间的阻塞需求。

### 8.3 实际防御体系

| Phase 2 检查 | 检测信号 | 覆盖路径 |
|---|---|---|
| `session_compacting` | Gateway log precheck 开始标记 + jsonl 结束标记 | precheck |
| `session_locked` | Lock file 存在 + PID 活 | 全部（precheck + manual + threshold） |

两条路径互补，先命中哪个就 skip。V5 compact 检测是附加保险，不是唯一防线。

### 8.4 自身 compact 验证（庞统）

同日 08:00 对庞统自身执行 `/compact` 的结果一致：
- Gateway log 无开始标记，只有 `08:00:12.213` 的 `rotated active transcript`（结束）
- `sessions.compact 238358ms` ≈ 3 分 58 秒
- 结论相同

## 9. 评审记录

- **v1**：trajectory jsonl 间接推断 → 仲达指出 trajectoryPath 不可用、需多文件等 3 个问题
- **v2**：gateway 日志 precheck 开始标志 → 仲达指出开始标志覆盖率仅 30%，建议 rotation-only
- **v3**：rotation-only + 120s 窗口 → 合并 PR #36，但实测 51 分钟 compact loop 无法覆盖
- **v4**：trajectory prompt.submitted → 仲达背靠背验证（源码 7 条 skipPromptSubmission 路径 + 实际数据 ~8% 假阳性但方向安全）→ 修正检测目标为"session 是否正常"
- **v5**：gateway log（precheck 开始标记）+ jsonl（compaction 结束标记）配对 → 仲达评审通过后实现，PR #48 Review 驳回 M1/M2 修正后合并

> ⚠️ **v4 已 deprecated**。v4 的 trajectory prompt.submitted 方案未实施，最终实施的是 v5。v4 的分析（skipPromptSubmission 路径、实测数据）仍有参考价值。