# Changelog — BUG Batch 5：心跳 TTL / 远程写 ETag（2026-06-04）

## 摘要

将 Agent 心跳 Redis TTL 调整为 flush 间隔的 1.5 倍，并补全远程写/chmod/压缩/解压后的 browse ETag 失效。

## 动机

- 注释要求 TTL 大于 10min flush，但 `REDIS_KEY_EXPIRE` 与 `FLUSH_INTERVAL` 同为 600s，停 Agent 后 key 可能先过期。
- Batch 4 仅覆盖 file-ops/upload/clipboard，写文件与 chmod 等仍会导致目录列表 304 陈旧。

## 变更

| 文件 | 说明 |
|------|------|
| `server/api/agent.py` | `REDIS_KEY_EXPIRE = int(FLUSH_INTERVAL * 1.5)` |
| `server/background/heartbeat_flush.py` | 移除重复 TTL 常量，注释指向 agent |
| `server/application/services/files_browse_service.py` | `invalidate_browse_parents()` |
| `server/api/sync_v2.py` | write/chmod/compress/decompress 后失效父目录缓存 |
| `server/background/self_monitor.py` | debug 日志增加 `ws_sync_clients` |
| `tests/test_agent_heartbeat_ttl.py` | TTL > flush 断言 |
| `tests/test_files_browse_etag.py` | `invalidate_browse_parents` 单测 |

## 迁移 / 重启

- 需重启 `nexus`。
- 无 DB 迁移；已有 Redis key 在下次心跳时刷新 TTL。

## 验证

```bash
ruff check server/api/agent.py server/api/sync_v2.py
pytest tests/test_agent_heartbeat_ttl.py tests/test_files_browse_etag.py tests/ -q
```

## 关联

- Batch 4：`docs/changelog/2026-06-04-bug-batch4-push-etag-heartbeat.md`