cursor-guard 4.5.1 → 4.5.5

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.5.1`（V4 最终版）  
-> **文档状态**：`V2` ~ `V4.5.1` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.5.5`（V4 最终版）  
+> **文档状态**：`V2` ~ `V4.5.5` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -459,6 +459,9 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | V4.4.0 | **V4 收官版**：首次快照 summary（无 parent 时生成 Added N: ...）；doctor 新增 Git retention 警告（>500 commits + disabled）和 Backup integrity 校验（`cat-file -t` tree 可达性）；`cursor-guard-init` 升级检测（已有配置提示） | ✅ |
 | V4.4.1 | **安全硬化版（5 项审计修复 + UX 优化）**：见下方详细说明 | ✅ |
 | V4.5.0 | **V4 最终版（异常检测修复 + Dashboard 全面升级）**：见下方详细说明 | ✅ 收官 |
+| V4.5.2 | **告警结构化文件列表**：见下方详细说明 | ✅ |
+| V4.5.3 | **告警历史 UX 优化 + 备份结构化文件表格**：见下方详细说明 | ✅ |
+| V4.5.4 | **Shadow 硬链接增量优化 + always_watch 强保护模式**：见下方详细说明 | ✅ |
 
 #### V4.4.1 详细内容
 
@@ -512,6 +515,134 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 
 > **注**：V4.2 的 Web 仪表盘最初在 V4.0 规划中标记为"不做"，但用户需求明确后实施。事实证明只读仪表盘投入产出比合理，且不违反安全原则。
 
+#### V4.5.2 详细内容
+
+**告警结构化文件列表**：
+
+| 层 | 改动 | 说明 |
+|----|------|------|
+| Core | `snapshot.js` 返回 `changedFiles` 数组 | 每项包含 `{ path, action, added, deleted }`，数据来源 `diff-tree --numstat`，按变化量降序排列 |
+| Core | `auto-backup.js` 透传 `changedFiles` | `createGitSnapshot` → `recordChange(tracker, count, changedFiles)` |
+| Core | `anomaly.js` alert 携带 `files` 字段 | 窗口内多次事件的文件按路径去重合并，最多保留 50 条，`saveAlert` 持久化到磁盘 |
+| Dashboard | 告警卡片可展开文件详情表格 | 点击"展开文件详情"显示排序表格（文件路径 / 操作类型 / 变化量），操作类型用彩色 badge 区分（修改=蓝 / 新增=绿 / 删除=红 / 重命名=紫） |
+| Dashboard | i18n 补全 | 新增 8 个双语 key（showFiles / hideFiles / col.file / col.action / col.changes / action.*） |
+
+> 22 个文件被删除和 22 个文件被新增的风险完全不同——结构化文件列表让用户一眼判断严重程度。
+
+#### V4.5.3 详细内容
+
+**告警历史 UX 修复**：
+
+| 问题 | 修复 | 实现细节 |
+|------|------|----------|
+| 告警过期后，"无活跃告警"绿色状态下方直接展示历史记录，上面说没事、下面列了两条记录，信息矛盾 | 历史默认完全隐藏，只显示灰色"历史（N 条）"可点击文字，展开后才显示历史列表 | `renderAlertCard` 无活跃告警分支：新增 `alert-history-toggle-btn`（灰色 11px 可点击按钮）+ `.alert-history-collapsed`（CSS `display:none`）。事件委托 `[data-alert-history-toggle]` 绑定在 `#card-alert` 上，toggle `alert-history-collapsed` class |
+
+告警卡片状态设计：
+
+```
+无告警时：
+  ✅ 无活跃告警
+  历史（2 条）  ← 灰色小字，点击展开
+
+有告警时：
+  ⚠ 活跃告警
+  13:03:54 触发 · 剩余 1m 53s
+  22 个文件在 10 秒内变更（阈值：20）
+  [展开文件详情]
+```
+
+**备份结构化文件表格**：
+
+| 层 | 改动 | 说明 |
+|----|------|------|
+| Core | `backups.js` 新增 `getBackupFiles(projectDir, commitHash)` | 对指定 commit 运行 `diff-tree --numstat + --name-status`，返回 `[{path, action, added, deleted}]`，按变化量降序。支持 rename 解析（`R` 前缀→取 tab 分割的最后一段）。无 parent 时退化为 `ls-tree` 列出全部文件 |
+| Server | `GET /api/backup-files?id=<project>&hash=<commit>` | 懒加载端点，不在 `list_backups` 中批量计算（50 条备份×`diff-tree` 会很慢）。400 校验 `hash` 必填 |
+| Dashboard | `parseSummaryToFiles(summary)` | 解析 summary 文本格式 `"Modified 3: a.js (+2 -1), b.js (+0 -5), ...; Added 2: c.js (+10 -0)"` → `[{path, action, added, deleted}]`。正则匹配 `(Modified|Added|Deleted|Renamed) N:` 段头，逐文件解析 `filename (+N -M)`，自动跳过 `...` 截断标记 |
+| Dashboard | `fetchBackupFiles(hash)` | 调用 `/api/backup-files` 端点，返回完整文件数组。网络失败静默降级（返回空数组） |
+| Dashboard | 备份表 `formatSummaryCell` | 行内 mini 文件表格：`parseSummaryToFiles` 取前 3 个文件，每文件显示路径（mono 字体 11px，`max-width:220px` 省略号截断）+ 操作 badge（彩色）+ `+N -M`。超出显示"等 N 个文件…"（斜体灰色），`N` 取 `filesChanged` 字段（当 summary 有 `...` 截断时）或实际剩余数 |
+| Dashboard | 抽屉 `openRestoreDrawer` | summary 字段不再用 `<pre>` 文本，改为懒加载可排序文件表格。打开抽屉 → `fetchBackupFiles(hash)` → `renderDrawerFilesTable(files, sortKey)`。三列表头均可点击排序（path=字典序 / action=字母序 / changes=变化量降序），当前排序列高亮。API 失败时降级为 `parseSummaryToFiles` 本地解析 |
+| Dashboard | `renderDrawerFilesTable(files, sortKey)` | 可排序表格渲染函数：sticky 表头、340px 最大高度滚动区域、表头带 ↕ 排序指示器、行内复用 `formatFileActionBadge` 统一操作 badge |
+| Dashboard | i18n 补全 | 新增 `summary.andMore`（"and {n} more…" / "等 {n} 个文件…"）、`alert.historyCount`（"History ({n})" / "历史（{n} 条）"） |
+
+> 同一个 `getBackupFiles` 数据结构，告警详情和备份详情两个地方同时受益。备份表行内看 3 个关键文件，抽屉里看完整列表——信息层级清晰，不再一行文本挤 22 个文件名。
+
+#### V4.5.4 详细内容
+
+**Shadow 硬链接增量优化**：
+
+| 层 | 改动 | 说明 |
+|----|------|------|
+| Core | `snapshot.js` `findPreviousSnapshot(backupDir)` | 新增辅助函数。扫描 backupDir 下所有 `YYYYMMDD_HHMMSS` 格式目录，按时间戳降序排列，返回最新的 snapshot 目录路径（`isDirectory` 校验） |
+| Core | `snapshot.js` `createShadowCopy` 硬链接逻辑 | 备份循环中，对每个文件执行增量判断：① 读取源文件 `stat`（size + mtimeMs）② 读取上一个 snapshot 同路径文件 `stat` ③ 若 size 完全一致且 mtimeMs 差值 < 1ms → `fs.linkSync(prevFile, dest)` 硬链接 ④ 否则 → `fs.copyFileSync(src, dest)` + `fs.utimesSync(dest, atime, mtime)` 保留源文件时间戳 |
+| Core | mtime 保留策略 | 每次 `copyFileSync` 后立即 `utimesSync` 将源文件的 mtime 同步到目标。这确保下一次 shadow 备份时，"上一个 snapshot 的文件 mtime" = "当时源文件的 mtime"，硬链接比较才有基准。`utimesSync` 失败不阻塞备份（`try-catch` 静默） |
+| Core | 跨卷容错 | `fs.linkSync` 在跨文件系统（如 backupDir 在不同磁盘卷）或 FAT32 分区上会抛 `EXDEV` 错误。外层 `try-catch` 捕获后自动 fall back 到 `copyFileSync`，不影响备份正确性 |
+| Watcher | `auto-backup.js` 日志 | Shadow 日志增加硬链接统计：`Shadow copy 20260322_130000 (150 files [142 hard-linked])`。linkedCount = 0 时不显示 |
+| 返回值 | `createShadowCopy` 新增 `linkedCount` 字段 | 表示本次备份中通过硬链接节省 I/O 的文件数。用于日志、Dashboard 未来可展示 |
+
+性能对比：
+
+| 场景 | 文件总数 | 变更数 | 传统全量 copy | 硬链接增量 | 磁盘节省 |
+|------|---------|--------|--------------|-----------|---------|
+| 常规开发 | 150 | 8 | 150 次 copy | 8 copy + 142 link | ~95% I/O |
+| 大规模重构 | 150 | 50 | 150 次 copy | 50 copy + 100 link | ~67% I/O |
+| 首次备份 | 150 | 150 | 150 次 copy | 150 次 copy（无上一个 snapshot） | 0%（正常） |
+
+> 硬链接在 NTFS（Windows）和 ext4/APFS（Linux/macOS）上均支持。同一 inode 共享磁盘块，150 个文件只改 8 个时磁盘写入降 95%。
+
+**always_watch 强保护模式**：
+
+| 层 | 改动 | 说明 |
+|----|------|------|
+| Config | `utils.js` DEFAULT_CONFIG | 新增 `always_watch: false` 默认配置项 |
+| Config | `utils.js` loadConfig | 解析 `.cursor-guard.json` 中的 `always_watch` 布尔值。类型校验：非 `true`/`false` 值 → 警告 + 使用默认值 `false` |
+| MCP | `mcp/server.js` `watchedProjects` Map | 进程级 Map，`key = projectPath`，`value = { pid, external }`。追踪已启动/检测到的 watcher，防止重复 spawn |
+| MCP | `mcp/server.js` `ensureWatcher(projectPath)` | 自动 watcher 管理器，执行流程：① `watchedProjects.has(path)` → 已处理过则跳过 ② `loadConfig(path)` → 检查 `always_watch` 是否为 `true` ③ `isWatcherRunning(path)` → 已有外部 watcher 则标记 `external: true` 跳过 ④ `spawn(process.execPath, [cursor-guard-backup, --path, path])` → 创建 detached 子进程（`detached: true, stdio: 'ignore', windowsHide: true`） ⑤ `child.unref()` → 父进程退出不影响 watcher |
+| MCP | 所有 9 个 tool handler | 入口处统一调用 `ensureWatcher(resolved)`。仅首次调用触发实际逻辑，后续调用通过 Map 缓存直接跳过（O(1)） |
+| 安全 | 与现有锁文件机制兼容 | `ensureWatcher` 先检查 `isWatcherRunning`（读取 lock file + `process.kill(pid, 0)` PID 存活检测），不会在已有 watcher 时重复启动。手动启动的 watcher 和 auto-spawn 的 watcher 使用同一个 lock file，互斥保护 |
+
+用户配置方式：
+```json
+{
+  "always_watch": true
+}
+```
+
+两种保护模式对比：
+
+| | 轻量模式（默认） | 强保护模式 |
+|---|---|---|
+| 配置 | `always_watch: false`（或不设） | `always_watch: true` |
+| Watcher 启动 | 手动 `cursor-guard-backup` | MCP server 首次 tool 调用自动 spawn |
+| 保护覆盖 | AI 需手动 `snapshot_now` | 全程自动备份，零保护缺口 |
+| 适用场景 | 小项目、低频编辑 | 重要项目、高频 AI 协作 |
+| 资源开销 | 无后台进程 | 后台 watcher 进程（低 CPU，周期性扫描） |
+
+> 这个特性直接填补了 V4 最大的架构缺口——"Watcher 停止 = 裸奔"。详见下方"V4 遗留的架构缺口"中该条目已标记为 **已解决**。
+
+#### V4.5.x 新增配置参考
+
+| 字段 | 类型 | 默认值 | 引入版本 | 说明 |
+|------|------|--------|---------|------|
+| `always_watch` | `boolean` | `false` | V4.5.4 | 强保护模式。设为 `true` 后，MCP server 首次 tool 调用自动启动 watcher 进程 |
+
+完整 `.cursor-guard.json` 配置示例（含 V4.5.4 新增项）：
+
+```json
+{
+  "protect": ["src/**", "*.config.js"],
+  "ignore": ["node_modules/**", "dist/**"],
+  "backup_strategy": "git",
+  "auto_backup_interval_seconds": 60,
+  "always_watch": true,
+  "proactive_alert": true,
+  "alert_thresholds": {
+    "files_per_window": 20,
+    "window_seconds": 10,
+    "cooldown_seconds": 60
+  }
+}
+```
+
 ### V4 不做的事
 
 - 不做自动恢复（恢复永远需要人确认，这是产品底线）
@@ -522,18 +653,19 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 
 通过 V4.4.1 的安全审计和真实场景测试，发现以下架构层面的保护缺口。这些不是代码 bug，而是设计边界：
 
-| 缺口 | 现状 | 影响 | V5 改进方向 |
-|------|------|------|------------|
-| **Watcher 停止 = 裸奔** | Watcher 不运行期间的文件变更无任何自动备份 | 如果 AI agent 也没手动 snapshot，变更永久丢失 | **`always_watch` 配置项**：在 `.cursor-guard.json` 中设置 `"always_watch": true`，MCP server 启动时自动 fork watcher 进程。用户可选两种模式：轻量模式（默认，AI 手动 snapshot）和强保护模式（watcher 始终在后台） |
-| **保护依赖 AI 自觉** | SKILL.md 要求 AI 在写入前 snapshot，但没有强制机制 | AI 不遵守协议就直接写，保护形同虚设 | **embedded watcher + `begin_edit` 意图绑定**：MCP server 内嵌 watcher 循环 + 按文件路径匹配 intent，消除进程边界和并发竞争（详见 V5 设计） |
-| **自动备份无意图上下文** | auto-backup 只有 `trigger: auto`，不知道是谁改的、为什么改 | 事后回溯只能看到时间点快照，不知道操作意图 | **`begin_edit` → 文件路径绑定**：AI 编辑前声明意图和目标文件，embedded watcher 检测变更时按路径匹配 intent，自动备份也能带上下文 |
-| **无跨进程写拦截** | 当前 MCP 架构下无法拦截 Cursor 编辑器的文件写入 | 只能在写后检测，不能写前阻止 | 等待 MCP 协议支持 `notification` / `resource subscription`，或探索 fs watch + pre-commit 组合 |
-| **意图队列并发问题** | 曾考虑"意图队列"（AI 写文件 → watcher 读文件关联 intent），但存在 4 类并发竞态：多 Agent 竞争、意图-变更错位、意图堆积、空意图残留 | 文件 I/O 跨进程 + 时间顺序绑定 = 不可靠 | **同进程内存 Map + 文件路径绑定**：消灭进程边界后无 IPC，按路径而非时间匹配消除歧义（详见 V5 设计） |
+| 缺口 | 现状 | 影响 | V5 改进方向 | 状态 |
+|------|------|------|------------|------|
+| ~~**Watcher 停止 = 裸奔**~~ | ~~Watcher 不运行期间无自动备份~~ | ~~变更永久丢失~~ | ~~`always_watch` 配置项~~ | ✅ **V4.5.4 已解决**：`always_watch: true` 时 MCP server 首次 tool 调用自动 spawn watcher 进程，与现有锁文件互斥机制兼容 |
+| **保护依赖 AI 自觉** | SKILL.md 要求 AI 在写入前 snapshot，但没有强制机制 | AI 不遵守协议就直接写，保护形同虚设 | **embedded watcher + `begin_edit` 意图绑定**：MCP server 内嵌 watcher 循环 + 按文件路径匹配 intent，消除进程边界和并发竞争（详见 V5 设计） | 🔮 V5 |
+| **自动备份无意图上下文** | auto-backup 只有 `trigger: auto`，不知道是谁改的、为什么改 | 事后回溯只能看到时间点快照，不知道操作意图 | **`begin_edit` → 文件路径绑定**：AI 编辑前声明意图和目标文件，embedded watcher 检测变更时按路径匹配 intent，自动备份也能带上下文 | 🔮 V5 |
+| **无跨进程写拦截** | 当前 MCP 架构下无法拦截 Cursor 编辑器的文件写入 | 只能在写后检测，不能写前阻止 | 等待 MCP 协议支持 `notification` / `resource subscription`，或探索 fs watch + pre-commit 组合 | 🔮 V5+ |
+| **意图队列并发问题** | 曾考虑"意图队列"（AI 写文件 → watcher 读文件关联 intent），但存在 4 类并发竞态：多 Agent 竞争、意图-变更错位、意图堆积、空意图残留 | 文件 I/O 跨进程 + 时间顺序绑定 = 不可靠 | **同进程内存 Map + 文件路径绑定**：消灭进程边界后无 IPC，按路径而非时间匹配消除歧义（详见 V5 设计） | 🔮 V5 |
 
 ### 进入 V5 的衡量标准
 
-- V4 的主动提醒功能误报率 < 10%
-- 健康看板的信息准确度经用户验证
+- ✅ V4 的主动提醒功能误报率 < 10% — V4.5.0 修复了计数数据源（`diff-tree` 替代 `porcelain`）
+- ✅ 健康看板的信息准确度经用户验证 — V4.5.2-V4.5.3 增加结构化文件列表，数据来源一致
+- ✅ `always_watch` 基础能力可用 — V4.5.4 已实现（spawn 独立进程版）
 - 多 Agent 并发编辑已成为用户的真实场景（不是假设）
 - MCP 协议的 notification / resource subscription 机制已相对成熟
 
@@ -543,10 +675,12 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 
 | 项目 | 内容 |
 |---|---|
-| 状态 | 中期主线 🚀 |
+| 状态 | 中期主线 🚀（V4.5.x 已完成基础设施前置） |
 | 定位 | 从保护"一次 AI 写操作"升级为管理"整条 AI 代码变更链路"：事前预防、事中判断、事后追溯、按事件恢复。 |
 | 产品定义 | `AI Code Change Control Layer` |
 | 关键词 | `intent` / `impact` / `audit` / `restore-by-event` |
+| V4 前置 | `always_watch`（V4.5.4）、结构化文件数据（V4.5.2-V4.5.3）、intent 基础（V4.3.3）、审计 trailer（V4.3.0）、Shadow 硬链接（V4.5.4）、Web 仪表盘（V4.2-V4.5.3） |
+| V5 核心差异 | **embedded watcher（同进程）** + **begin_edit 意图-变更原子绑定** — 这两项是 V4 无法做到的，需要架构升级 |
 
 ### 为什么需要这一步
 
@@ -567,29 +701,35 @@ V2-V4 已经证明，cursor-guard 的价值不只是"多留一个备份点"，
 
 V5 不是"三个方向选一个"，而是把下面这条链路做完整：
 
-1. **Intent**：谁正准备改这里？
-2. **Impact**：这次改动会波及哪里？
-3. **Audit**：这段代码何时、被谁、因何改的？
-4. **Restore**：出事后该回退哪次操作？
+| 步骤 | 核心问题 | V4 已有基础 | V5 新增 |
+|------|---------|------------|---------|
+| **Intent** | 谁正准备改这里？ | ✅ `snapshot_now` intent/agent/session 参数 | `begin_edit` 实时注册 + 文件路径绑定 |
+| **Impact** | 这次改动波及哪里？ | ✅ 结构化 `changedFiles` + `getBackupFiles` | 符号级分析（导出/引用/测试波及） |
+| **Audit** | 何时、被谁、因何改的？ | ✅ Git trailer 审计元数据 + 仪表盘展示 | 独立 JSONL 审计存储 + 结构化事件查询 |
+| **Restore** | 出事回退哪次操作？ | ✅ `restore_file` / `restore_project` + pre-restore 快照 | `restore_from_event`（按事件 ID 直接恢复） |
 
-只有这四步连起来，cursor-guard 才不是"备份工具"，而是"变更控制层"。
+只有这四步连起来，cursor-guard 才不是"备份工具"，而是"变更控制层"。V4 已铺好每一步的基础设施，V5 的核心价值是把它们**原子化串联**——通过同进程 embedded watcher + 文件路径意图绑定，让 Intent → Impact → Audit → Restore 在一个事件链里自动完成。
 
 ### V5.0 可执行功能清单
 
-| 模块 / 能力 | AI 要做什么 | 建议产物 | 完成标准 |
+> **注**：部分 V5 规划能力已在 V4.5.x 提前落地，下表用 ✅ 标注。V5 的核心差异化在于 **embedded watcher（同进程）** 和 **begin_edit 意图-变更原子绑定**。
+
+| 模块 / 能力 | 说明 | V4 已落地 | V5 新增 |
 |---|---|---|---|
-| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件。**基础版已在 V4.3.3 落地**：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，存储为 Git commit trailer，仪表盘可展示。**V4.3.5 修复**：summary 改用 `diff-tree` 增量对比，确保元数据准确 |
-| `pre-edit snapshot` | 在每次高风险 AI 写入前创建 `refs/guard/pre-edit/*` 恢复点 | `refs/guard/pre-edit/<session>/<seq>` | 任意一条 AI 编辑事件都能关联到写前快照 |
-| `conflict detection` | 先做文件路径级冲突检测，再预留符号级增强位 | `detectConflicts()` / `listConflicts()` | 两个会话同时改重叠文件时能给出 advisory warning |
-| `audit store` | 以 append-only 方式保存 AI 编辑事件 | 默认本地 `JSONL`；后续可升级 `SQLite` | 能按文件 / 会话 / agent / 时间 / 风险级别查询。**雏形已在 V4.3.0-V4.3.3 落地**：审计元数据通过 Git commit trailer 持久化，`listBackups` 可按 trigger/intent/agent/session 解析 |
-| `restore by event` | 允许从一条审计事件直接跳转并执行恢复 | `restore_from_event` | 给定 `event_id` 可以定位 `before_ref` 或 `restore_ref` |
-| `impact set` | 为高风险编辑记录受影响文件 / 符号 / 测试集合 | `impact_set` 字段 | 查询事件时能看到"这次改动可能波及哪里" |
-| `MCP / CLI surface` | 暴露最小可用接口给 Agent 和终端 | `register_intent` / `list_active_intents` / `audit_query` / `get_event` / `restore_from_event` | AI 不需要拼复杂 shell，就能完成查询与恢复 |
-| `dashboard / doctor` | 把活跃会话、冲突告警、最近 AI 事件纳入诊断和看板 | `dashboard` / `doctor` 扩展字段 | 用户能看见"现在谁在改、最近改了什么、哪里有冲突" |
-| `always_watch` | 配置项 `"always_watch": true`，MCP server 启动时自动内嵌 watcher 循环；用户可选两种保护模式：**轻量模式**（默认，AI 手动 `snapshot_now`）vs **强保护模式**（watcher 始终在后台，所有变更自动备份） | `.cursor-guard.json` 配置 + MCP server 启动逻辑 | MCP server 启动后，`always_watch: true` 的项目自动有 watcher 保护，无需额外命令；选择权在用户 |
-| `embedded watcher` | **消灭进程边界**：不再是独立后台进程，而是 MCP server 同进程内的 watcher 循环。同进程 = 无 IPC、无文件桥接、无并发竞争。检测到文件变更时自动创建 snapshot，不依赖 AI 手动调用 | MCP server 内部模块 | watcher 停止 = 裸奔的保护缺口彻底消除；AI 忘记 snapshot 也有兜底 |
-| `begin_edit` / `end_edit` | **意图-变更原子绑定**：AI 编辑前调 `begin_edit({ intent, files[], agent, session })`，在内存 `Map<session, EditScope>` 注册编辑意图和目标文件。embedded watcher 检测到变更时按**文件路径**匹配 intent，自动备份带完整上下文。`end_edit(session)` 或 TTL（默认 5 分钟）自动清除 | `begin_edit` / `end_edit` MCP 工具 + 内存 `activeEdits` Map | auto-backup 也能带 intent/agent/session；并发多 Agent 按文件路径消歧，不按时间顺序 |
-| `tests / docs` | 为事件链路补齐单测、集成测试和文档 | tests + schema docs | V5.0 的所有核心事件和恢复路径都有测试覆盖 |
+| `intent registry` | 注册编辑意图（agent、会话、目标文件、风险级别） | ✅ V4.3.3：`snapshot_now` 支持 `intent/agent/session`，Git trailer 存储，仪表盘展示 | 升级为 `begin_edit` MCP 工具，内存 Map 管理活跃会话，支持文件路径级冲突检测 |
+| `pre-edit snapshot` | 每次高风险写入前创建恢复点 | ✅ V4：`restore_file` / `restore_project` 自动创建 `refs/guard/pre-restore/*` | 新增 `refs/guard/pre-edit/<session>/<seq>`，按会话隔离 |
+| `conflict detection` | 并发编辑冲突告警 | — | 新增：`begin_edit` 时检测文件路径重叠，advisory warning |
+| `audit store` | 审计事件存储与查询 | ✅ V4.3.0-V4.3.3：Git commit trailer 持久化（trigger/intent/agent/session），`listBackups` 可解析 | 升级为独立 JSONL 审计存储，支持按事件 ID / 文件 / 会话 / 风险级别查询 |
+| `restore by event` | 从审计事件直接恢复 | — | 新增：`restore_from_event(event_id)` → 定位 `before_ref` → 执行恢复 |
+| `impact set` | 记录变更波及范围 | ✅ V4.5.2：告警携带结构化文件列表 `[{path, action, added, deleted}]` | 升级：增加符号级分析（导出/引用变更检测） |
+| `MCP / CLI surface` | 变更控制接口 | ✅ V4：9 个 MCP 工具（doctor / list_backups / snapshot_now / restore_file / restore_project / doctor_fix / backup_status / dashboard / alert_status） | 新增：`begin_edit` / `end_edit` / `audit_query` / `get_event` / `restore_from_event` |
+| `dashboard / doctor` | 看板和诊断 | ✅ V4.2-V4.5.3：完整 Web 仪表盘，告警卡片+历史、备份表格+抽屉、诊断面板、结构化文件表格 | 扩展：活跃会话面板、冲突告警卡片、AI 事件时间线 |
+| `always_watch` | 强保护模式 | ✅ **V4.5.4 已完整实现**：`always_watch: true` → MCP server 首次 tool 调用自动 spawn watcher 进程，`ensureWatcher()` + `watchedProjects` Map + 锁文件互斥兼容 | V5 进一步升级为 embedded watcher（同进程内嵌，非独立进程） |
+| `embedded watcher` | 同进程 watcher 循环 | 部分：V4.5.4 `always_watch` 通过 spawn 独立子进程实现（解决了"裸奔"问题，但仍是跨进程） | **核心差异**：MCP server 内嵌 watcher 循环，同进程=无 IPC、无竞争。检测变更时按文件路径匹配 `begin_edit` 中的 intent |
+| `begin_edit` / `end_edit` | 意图-变更原子绑定 | — | **核心新增**：`begin_edit({ intent, files[], agent, session })` → 内存 `Map<session, EditScope>` → watcher 按文件路径匹配 → auto-backup 带完整上下文。`end_edit` 或 TTL 5min 自动清除 |
+| `Shadow 增量优化` | 节省磁盘 I/O | ✅ **V4.5.4 已完整实现**：硬链接未变文件（mtime+size 比较），mtime 保留，跨卷容错，日志显示 linkedCount | — |
+| `备份结构化文件数据` | 结构化 files 数组 | ✅ **V4.5.2-V4.5.3 已完整实现**：snapshot changedFiles、anomaly alert files、`getBackupFiles` API、前端 mini 表格+抽屉可排序表格 | — |
+| `tests / docs` | 测试和文档 | ✅ V4：138 测试全过（utils 39 + core 78 + MCP 21） | 为 V5 新增事件链路补齐测试 |
 
 ### V5 核心设计：Embedded Watcher + 文件路径意图绑定
 
@@ -658,8 +798,15 @@ MCP Server 进程（知道 intent）  ←——×——→  Watcher 进程（知
 #### 实现分期
 
 ```
-Phase 1 (V5.0):
-  ├── always_watch: true → MCP server 内嵌 watcher 循环
+Phase 0 (V4.5.x — ✅ 已完成):
+  ├── always_watch: true → MCP server 自动 spawn watcher 子进程（V4.5.4）
+  ├── 结构化文件数据：snapshot changedFiles + alert files + getBackupFiles API（V4.5.2-V4.5.3）
+  ├── Shadow 硬链接增量优化（V4.5.4）
+  ├── 告警历史 UX + 备份文件表格化（V4.5.3）
+  └── intent/agent/session 基础支持（V4.3.3）
+
+Phase 1 (V5.0 — 核心差异化):
+  ├── always_watch 升级：从 spawn 独立进程 → MCP server 内嵌 watcher 循环（同进程）
   ├── 新增 begin_edit / end_edit MCP 工具
   ├── 内存 Map<session, EditScope> 管理活跃编辑意图
   └── watcher 变更检测时查 Map，按文件路径匹配 intent → 写入 commit trailer
@@ -807,7 +954,8 @@ V5 的关键不是"多打一行日志"，而是建立完整证据链：
 
 ### V5 完成标志（Definition of Done）
 
-- `always_watch: true` 配置生效后，MCP server 启动自动内嵌 watcher 循环，用户无需额外命令
+- ~~`always_watch: true` 配置生效后，用户无需额外命令~~ → ✅ **V4.5.4 已完成**（spawn 子进程方式）
+- V5 升级：`always_watch` 从 spawn 子进程升级为 MCP server 内嵌 watcher 循环（同进程，无 IPC）
 - `begin_edit` / `end_edit` MCP 工具可用，AI 能声明编辑意图和目标文件
 - embedded watcher 的自动备份能通过文件路径匹配关联 `begin_edit` 中的 intent/agent/session
 - 无 `begin_edit` 时自动备份行为与 V4 一致（无退化）
@@ -815,7 +963,8 @@ V5 的关键不是"多打一行日志"，而是建立完整证据链：
 - 用户能查询最近一次 AI 编辑的完整上下文
 - 给定 `event_id` 能找到对应快照并执行恢复
 - 两个活跃会话改同一文件时，系统能稳定给出冲突告警
-- dashboard / doctor 能展示最近 AI 事件、活跃会话和未解决冲突
+- ~~dashboard / doctor 展示告警、备份详情~~ → ✅ **V4.2-V4.5.3 已完成**（Web 仪表盘、告警卡片+历史、结构化文件表格、可排序抽屉）
+- V5 扩展：dashboard 增加活跃会话面板、冲突告警卡片、AI 事件时间线
 
 ### 进入 V6 的衡量标准
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.5.1",
+  "version": "4.5.5",
   "description": "Protects code from accidental AI overwrite or deletion in Cursor IDE — mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery. | 保护代码免受 Cursor AI 代理意外覆写或删除——强制写前快照、预览再执行、本地 Git 安全网、确定性恢复。",
   "keywords": [
     "cursor",

package/references/dashboard/public/app.js

@@ -46,6 +46,16 @@ const I18N = {
     'alert.expired':    'Expired',
     'alert.history':    'Recent Alert History',
     'alert.noHistory':  'No alert history',
+    'alert.historyCount':'History ({n})',
+    'alert.showFiles':  'Show file details',
+    'alert.hideFiles':  'Hide file details',
+    'alert.col.file':   'File',
+    'alert.col.action': 'Action',
+    'alert.col.changes':'Changes',
+    'alert.action.modified': 'Modified',
+    'alert.action.added':    'Added',
+    'alert.action.deleted':  'Deleted',
+    'alert.action.renamed':  'Renamed',
 
     'backups.gitCommits':       'Git Commits',
     'backups.shadowSnapshots':  'Shadow Snapshots',
@@ -107,6 +117,7 @@ const I18N = {
     'summary.deleted':      'Deleted',
     'summary.renamed':      'Renamed',
     'summary.files':        'files',
+    'summary.andMore':      'and {n} more…',
     'drawer.field.intent':  'Intent',
     'drawer.field.agent':   'Agent',
     'drawer.field.session': 'Session',
@@ -243,6 +254,16 @@ const I18N = {
     'alert.expired':    '已过期',
     'alert.history':    '近期告警历史',
     'alert.noHistory':  '暂无告警记录',
+    'alert.historyCount':'历史（{n} 条）',
+    'alert.showFiles':  '展开文件详情',
+    'alert.hideFiles':  '收起文件详情',
+    'alert.col.file':   '文件',
+    'alert.col.action': '操作',
+    'alert.col.changes':'变化量',
+    'alert.action.modified': '修改',
+    'alert.action.added':    '新增',
+    'alert.action.deleted':  '删除',
+    'alert.action.renamed':  '重命名',
 
     'backups.gitCommits':       'Git 提交数',
     'backups.shadowSnapshots':  '影子快照',
@@ -304,6 +325,7 @@ const I18N = {
     'summary.deleted':      '删除',
     'summary.renamed':      '重命名',
     'summary.files':        '个文件',
+    'summary.andMore':      '等 {n} 个文件…',
     'drawer.field.intent':  '操作意图',
     'drawer.field.agent':   'AI 模型',
     'drawer.field.session': '会话 ID',
@@ -829,6 +851,7 @@ function renderAlertCard(alerts) {
   if (!alerts?.active) {
     let historyHtml = '';
     if (state.alertHistory.length > 0) {
+      const count = state.alertHistory.length;
       const rows = state.alertHistory.slice(-5).reverse().map(h =>
         `<div class="alert-history-row text-sm text-muted">
           <span>${esc(formatTime(h.timestamp))}</span>
@@ -836,7 +859,13 @@ function renderAlertCard(alerts) {
           <span class="badge badge-expired">${t('alert.expired')}</span>
         </div>`
       ).join('');
-      historyHtml = `<div class="alert-history"><div class="alert-history-label text-sm">${t('alert.history')}</div>${rows}</div>`;
+      historyHtml = `
+        <div class="alert-history-toggle-wrap">
+          <button class="alert-history-toggle-btn text-sm text-muted" data-alert-history-toggle>${t('alert.historyCount', { n: count })}</button>
+        </div>
+        <div class="alert-history alert-history-collapsed">
+          <div class="alert-history-label text-sm">${t('alert.history')}</div>${rows}
+        </div>`;
     }
     el.innerHTML = `
       <div class="card-label">${t('alert.title')}</div>
@@ -849,7 +878,7 @@ function renderAlertCard(alerts) {
 
   // Track in history
   if (a.timestamp && !state.alertHistory.some(h => h.timestamp === a.timestamp)) {
-    state.alertHistory.push({ timestamp: a.timestamp, fileCount: a.fileCount, windowSeconds: a.windowSeconds, threshold: a.threshold, expiresAt: a.expiresAt });
+    state.alertHistory.push({ timestamp: a.timestamp, fileCount: a.fileCount, windowSeconds: a.windowSeconds, threshold: a.threshold, expiresAt: a.expiresAt, files: a.files });
     if (state.alertHistory.length > 20) state.alertHistory = state.alertHistory.slice(-20);
   }
 
@@ -861,6 +890,32 @@ function renderAlertCard(alerts) {
   const remainDisplay = remainMin > 0 ? `${remainMin}m ${remainSec % 60}s` : `${remainSec}s`;
   const detailText = t('alert.detail', { count: a.fileCount || '?', window: a.windowSeconds || '?', threshold: a.threshold || '?' });
 
+  const files = Array.isArray(a.files) ? a.files : [];
+  let filesHtml = '';
+  if (files.length > 0) {
+    const actionBadge = (action) => {
+      const cls = action === 'deleted' ? 'alert-action-deleted'
+        : action === 'added' ? 'alert-action-added'
+        : action === 'renamed' ? 'alert-action-renamed'
+        : 'alert-action-modified';
+      return `<span class="alert-action-badge ${cls}">${t('alert.action.' + action)}</span>`;
+    };
+    const rows = files.map(f =>
+      `<tr><td class="text-mono alert-file-path">${esc(f.path)}</td><td>${actionBadge(f.action)}</td><td class="text-mono alert-file-changes">+${f.added || 0} -${f.deleted || 0}</td></tr>`
+    ).join('');
+    filesHtml = `
+      <div class="alert-files-section">
+        <button class="alert-files-toggle" data-alert-files-toggle>${t('alert.showFiles')}</button>
+        <div class="alert-files-table-wrap alert-files-hidden">
+          <table class="alert-files-table">
+            <thead><tr><th>${t('alert.col.file')}</th><th>${t('alert.col.action')}</th><th>${t('alert.col.changes')}</th></tr></thead>
+            <tbody>${rows}</tbody>
+          </table>
+        </div>
+      </div>
+    `;
+  }
+
   el.innerHTML = `
     <div class="card-label">${t('alert.title')}</div>
     <div class="card-status"><span class="status-dot status-warning"></span><span class="status-text status-warning">${t('alert.active')}</span></div>
@@ -869,6 +924,7 @@ function renderAlertCard(alerts) {
       <div class="alert-detail-row"><span class="alert-detail-label">${t('alert.expires')}</span><span class="alert-countdown">${esc(remainDisplay)}</span></div>
       <div class="alert-detail-row alert-numbers">${esc(detailText)}</div>
     </div>
+    ${filesHtml}
   `;
 }
 
@@ -935,6 +991,49 @@ function translateSummary(raw) {
     .replace(/\bRenamed (\d+)/g, (_, n) => `${t('summary.renamed')} ${n}`);
 }
 
+/**
+ * Parse summary text into structured file array for inline preview.
+ * Format: "Modified 3: a.js (+2 -1), b.js (+0 -5), ...; Added 2: c.js (+10 -0), d.js (+3 -0)"
+ */
+function parseSummaryToFiles(summary) {
+  if (!summary) return [];
+  const ACTION_MAP = { Modified: 'modified', Added: 'added', Deleted: 'deleted', Renamed: 'renamed' };
+  const files = [];
+  for (const segment of summary.split('; ')) {
+    const headerMatch = segment.match(/^(Modified|Added|Deleted|Renamed)\s+\d+:\s*/);
+    if (!headerMatch) continue;
+    const action = ACTION_MAP[headerMatch[1]] || 'modified';
+    const rest = segment.slice(headerMatch[0].length);
+    for (const part of rest.split(/,\s*/)) {
+      if (part === '...') continue;
+      const fileMatch = part.match(/^(.+?)\s*\(\+(\d+)\s+-(\d+)\)$/);
+      if (fileMatch) {
+        files.push({ path: fileMatch[1], action, added: parseInt(fileMatch[2], 10), deleted: parseInt(fileMatch[3], 10) });
+      } else if (part.trim()) {
+        files.push({ path: part.trim(), action, added: 0, deleted: 0 });
+      }
+    }
+  }
+  files.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
+  return files;
+}
+
+async function fetchBackupFiles(commitHash) {
+  if (!state.currentProjectId || !commitHash) return [];
+  try {
+    const data = await fetchJson(`/api/backup-files?id=${state.currentProjectId}&hash=${commitHash}`);
+    return Array.isArray(data.files) ? data.files : [];
+  } catch { return []; }
+}
+
+function formatFileActionBadge(action) {
+  const cls = action === 'deleted' ? 'alert-action-deleted'
+    : action === 'added' ? 'alert-action-added'
+    : action === 'renamed' ? 'alert-action-renamed'
+    : 'alert-action-modified';
+  return `<span class="alert-action-badge ${cls}">${t('alert.action.' + action)}</span>`;
+}
+
 function formatSummaryCell(b) {
   let line1 = '';
   if (b.filesChanged != null) {
@@ -955,15 +1054,20 @@ function formatSummaryCell(b) {
 
   let line3 = '';
   if (b.summary) {
-    const categories = b.summary.split('; ').map(s => translateSummary(s));
-    const MAX_VISIBLE = 2;
-    if (categories.length <= MAX_VISIBLE) {
-      line3 = categories.map(c => `<div class="summary-detail-line">${esc(c)}</div>`).join('');
+    const parsed = parseSummaryToFiles(b.summary);
+    if (parsed.length > 0) {
+      const MAX_INLINE = 3;
+      const visible = parsed.slice(0, MAX_INLINE).map(f =>
+        `<div class="summary-file-row"><span class="text-mono summary-file-path">${esc(f.path)}</span>${formatFileActionBadge(f.action)}<span class="text-mono text-muted">+${f.added} -${f.deleted}</span></div>`
+      ).join('');
+      const remaining = parsed.length > MAX_INLINE ? parsed.length - MAX_INLINE : 0;
+      const truncated = b.summary.includes('...');
+      const moreCount = truncated ? (b.filesChanged || '?') - MAX_INLINE : remaining;
+      const moreHtml = (remaining > 0 || truncated) ? `<div class="summary-file-more text-sm text-muted">${t('summary.andMore', { n: moreCount > 0 ? moreCount : '…' })}</div>` : '';
+      line3 = visible + moreHtml;
     } else {
-      const visible = categories.slice(0, MAX_VISIBLE).map(c => `<div class="summary-detail-line">${esc(c)}</div>`).join('');
-      const hidden = categories.slice(MAX_VISIBLE).map(c => `<div class="summary-detail-line">${esc(c)}</div>`).join('');
-      const more = categories.length - MAX_VISIBLE;
-      line3 = `${visible}<div class="summary-collapsed" data-summary-toggle>${hidden}</div><button class="summary-toggle-btn" data-summary-toggle>+${more} more</button>`;
+      const categories = b.summary.split('; ').map(s => translateSummary(s));
+      line3 = categories.slice(0, 2).map(c => `<div class="summary-detail-line">${esc(c)}</div>`).join('');
     }
   }
 
@@ -1095,6 +1199,24 @@ function closeDrawer() {
   state.drawerOpen = null;
 }
 
+function renderDrawerFilesTable(files, sortKey) {
+  const sorted = [...files];
+  if (sortKey === 'path') sorted.sort((a, b) => a.path.localeCompare(b.path));
+  else if (sortKey === 'action') sorted.sort((a, b) => a.action.localeCompare(b.action));
+  else sorted.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
+  const rows = sorted.map(f =>
+    `<tr><td class="text-mono drawer-file-path">${esc(f.path)}</td><td>${formatFileActionBadge(f.action)}</td><td class="text-mono drawer-file-changes">+${f.added} -${f.deleted}</td></tr>`
+  ).join('');
+  return `<table class="drawer-files-table">
+    <thead><tr>
+      <th data-sort="path" class="drawer-sort-header">${t('alert.col.file')} ↕</th>
+      <th data-sort="action" class="drawer-sort-header">${t('alert.col.action')} ↕</th>
+      <th data-sort="changes" class="drawer-sort-header">${t('alert.col.changes')} ↕</th>
+    </tr></thead>
+    <tbody>${rows}</tbody>
+  </table>`;
+}
+
 function openRestoreDrawer(backup) {
   const body = $('#restore-drawer-body');
   const fields = [
@@ -1113,10 +1235,6 @@ function openRestoreDrawer(backup) {
   if (backup.restoreTo) fields.push({ key: 'drawer.field.restoreTo', val: backup.restoreTo });
   if (backup.restoreFile) fields.push({ key: 'drawer.field.restoreFile', val: backup.restoreFile });
   if (backup.message) fields.push({ key: 'drawer.field.message', val: backup.message });
-  if (backup.summary) {
-    const translated = backup.summary.split('; ').map(s => translateSummary(s)).join('\n');
-    fields.push({ key: 'drawer.field.summary', val: translated, pre: true });
-  }
 
   const refText = backup.ref || backup.shortHash || backup.timestamp || '';
   const jsonText = JSON.stringify(backup, null, 2);
@@ -1130,12 +1248,17 @@ function openRestoreDrawer(backup) {
     ${fields.map(f => `
       <div class="restore-field">
         <div class="restore-field-label">${t(f.key)}</div>
-        ${f.pre
-          ? `<pre class="restore-field-value text-mono summary-pre">${esc(f.val)}</pre>`
-          : `<div class="restore-field-value text-mono">${esc(f.val)}</div>`
-        }
+        <div class="restore-field-value text-mono">${esc(f.val)}</div>
       </div>
     `).join('')}
+    ${backup.summary ? `
+    <div class="restore-field">
+      <div class="restore-field-label">${t('drawer.field.summary')}</div>
+      <div id="drawer-files-container" class="drawer-files-container">
+        <div class="drawer-files-loading text-muted text-sm">${t('state.loading')}</div>
+      </div>
+    </div>
+    ` : ''}
     <div class="restore-actions">
       <button class="btn btn-sm" data-copy="${esc(refText)}">${t('drawer.copyRef')}</button>
       <button class="btn btn-sm" data-copy-json>${t('drawer.copyJson')}</button>
@@ -1169,6 +1292,34 @@ function openRestoreDrawer(backup) {
     wrap.classList.toggle('hidden');
   });
 
+  // Lazy-load full file list for summary section
+  if (backup.summary && isGit && hash) {
+    let currentFiles = [];
+    let currentSort = 'changes';
+    fetchBackupFiles(hash).then(files => {
+      currentFiles = files.length > 0 ? files : parseSummaryToFiles(backup.summary);
+      const container = body.querySelector('#drawer-files-container');
+      if (container) {
+        container.innerHTML = renderDrawerFilesTable(currentFiles, currentSort);
+        container.addEventListener('click', (e) => {
+          const th = e.target.closest('[data-sort]');
+          if (!th) return;
+          currentSort = th.dataset.sort;
+          container.innerHTML = renderDrawerFilesTable(currentFiles, currentSort);
+        });
+      }
+    });
+  } else if (backup.summary) {
+    const fallback = parseSummaryToFiles(backup.summary);
+    const container = body.querySelector('#drawer-files-container');
+    if (container && fallback.length > 0) {
+      container.innerHTML = renderDrawerFilesTable(fallback, 'changes');
+    } else if (container) {
+      const translated = backup.summary.split('; ').map(s => translateSummary(s)).join('\n');
+      container.innerHTML = `<pre class="restore-field-value text-mono summary-pre">${esc(translated)}</pre>`;
+    }
+  }
+
   openDrawer('restore');
 }
 
@@ -1281,6 +1432,25 @@ function setupEvents() {
     if (backup) openRestoreDrawer(backup);
   });
 
+  // Alert history + files toggle (event delegation)
+  $('#card-alert').addEventListener('click', (e) => {
+    const historyToggle = e.target.closest('[data-alert-history-toggle]');
+    if (historyToggle) {
+      const card = historyToggle.closest('#card-alert');
+      const history = card?.querySelector('.alert-history');
+      if (history) history.classList.toggle('alert-history-collapsed');
+      return;
+    }
+    const toggleBtn = e.target.closest('[data-alert-files-toggle]');
+    if (!toggleBtn) return;
+    const section = toggleBtn.closest('.alert-files-section');
+    if (!section) return;
+    const wrap = section.querySelector('.alert-files-table-wrap');
+    if (!wrap) return;
+    const hidden = wrap.classList.toggle('alert-files-hidden');
+    toggleBtn.textContent = hidden ? t('alert.showFiles') : t('alert.hideFiles');
+  });
+
   // Diagnostics summary click
   $('#diagnostics-summary').addEventListener('click', (e) => {
     if (e.target.closest('#diag-summary-click')) openDoctorDrawer();

package/references/dashboard/public/style.css

@@ -418,6 +418,30 @@ main {
   border-left: 3px solid var(--blue);
 }
 
+/* ── Summary inline file rows ────────────────────────────── */
+
+.summary-file-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 1px 0;
+  font-size: 11px;
+  line-height: 1.4;
+}
+.summary-file-path {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 220px;
+  font-size: 11px;
+  color: var(--text-primary);
+}
+.summary-file-more {
+  padding: 2px 0;
+  font-style: italic;
+}
+
 /* ── Stats Row ────────────────────────────────────────────── */
 
 .stats-row {
@@ -749,6 +773,58 @@ main {
   line-height: 1.6;
 }
 
+/* ── Drawer: Files Table ──────────────────────────────────── */
+
+.drawer-files-container {
+  margin-top: 6px;
+  max-height: 340px;
+  overflow: auto;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+}
+.drawer-files-loading {
+  padding: 16px;
+  text-align: center;
+}
+.drawer-files-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12px;
+}
+.drawer-files-table th {
+  text-align: left;
+  padding: 8px 12px;
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+  color: var(--text-tertiary);
+  border-bottom: 1px solid var(--border-subtle);
+  background: var(--bg-elevated);
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+.drawer-sort-header { cursor: pointer; transition: color var(--transition); }
+.drawer-sort-header:hover { color: var(--blue); }
+.drawer-files-table td {
+  padding: 5px 12px;
+  border-bottom: 1px solid rgba(71,85,105,.15);
+  vertical-align: middle;
+}
+.drawer-file-path {
+  max-width: 280px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-primary);
+}
+.drawer-file-changes {
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+  color: var(--text-secondary);
+}
+
 /* ── Drawer: Doctor Checks ────────────────────────────────── */
 
 .check-item {
@@ -921,11 +997,26 @@ main {
   border-left: 3px solid var(--yellow);
 }
 
+.alert-history-toggle-wrap {
+  margin-top: 8px;
+}
+.alert-history-toggle-btn {
+  background: none;
+  border: none;
+  color: var(--text-tertiary);
+  font-size: 11px;
+  cursor: pointer;
+  padding: 2px 0;
+  transition: color var(--transition);
+}
+.alert-history-toggle-btn:hover { color: var(--blue); }
+
 .alert-history {
-  margin-top: 12px;
+  margin-top: 8px;
   border-top: 1px solid var(--border-subtle);
   padding-top: 8px;
 }
+.alert-history.alert-history-collapsed { display: none; }
 .alert-history-label {
   font-size: 10px;
   font-weight: 700;
@@ -949,6 +1040,84 @@ main {
   padding: 1px 6px;
 }
 
+/* ── Alert Files Table ───────────────────────────────────── */
+
+.alert-files-section {
+  margin-top: 10px;
+  border-top: 1px solid var(--border-subtle);
+  padding-top: 8px;
+}
+.alert-files-toggle {
+  background: none;
+  border: none;
+  color: var(--blue);
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 2px 0;
+  transition: color var(--transition);
+}
+.alert-files-toggle:hover { color: var(--text-heading); }
+
+.alert-files-table-wrap {
+  margin-top: 8px;
+  max-height: 220px;
+  overflow: auto;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+}
+.alert-files-hidden { display: none; }
+
+.alert-files-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 11px;
+}
+.alert-files-table th {
+  text-align: left;
+  padding: 6px 10px;
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+  color: var(--text-tertiary);
+  border-bottom: 1px solid var(--border-subtle);
+  background: var(--bg-elevated);
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+.alert-files-table td {
+  padding: 4px 10px;
+  border-bottom: 1px solid rgba(71,85,105,.15);
+  vertical-align: middle;
+}
+.alert-file-path {
+  max-width: 240px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-primary);
+}
+.alert-file-changes {
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+  color: var(--text-secondary);
+}
+
+.alert-action-badge {
+  display: inline-block;
+  padding: 1px 6px;
+  border-radius: 8px;
+  font-size: 9px;
+  font-weight: 600;
+  letter-spacing: .02em;
+}
+.alert-action-modified { background: var(--blue-bg); color: var(--blue); }
+.alert-action-added    { background: var(--green-bg); color: var(--green); }
+.alert-action-deleted  { background: var(--red-bg); color: var(--red); }
+.alert-action-renamed  { background: var(--purple-bg); color: var(--purple); }
+
 /* ── File Search ─────────────────────────────────────────── */
 
 .file-search-wrap {

package/references/dashboard/server.js

@@ -8,7 +8,7 @@ const path = require('path');
 
 const { getDashboard } = require('../lib/core/dashboard');
 const { runDiagnostics } = require('../lib/core/doctor');
-const { listBackups } = require('../lib/core/backups');
+const { listBackups, getBackupFiles } = require('../lib/core/backups');
 
 const PUBLIC_DIR = path.join(__dirname, 'public');
 const DEFAULT_PORT = 3120;
@@ -171,6 +171,13 @@ function handleApi(pathname, query, registry, res) {
     }
   }
 
+  if (pathname === '/api/backup-files') {
+    const hash = query.get('hash');
+    if (!hash) return json(res, { error: 'Missing hash parameter' }, 400);
+    try { return json(res, getBackupFiles(pp, hash)); }
+    catch (e) { return json(res, { error: e.message }, 500); }
+  }
+
   if (pathname === '/api/doctor') {
     try { return json(res, runDiagnostics(pp)); }
     catch (e) { return json(res, { error: e.message }, 500); }

package/references/lib/auto-backup.js

@@ -254,11 +254,13 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
     }
 
     // Git snapshot via Core — changedFileCount comes from diff-tree (accurate incremental)
+    let changedFiles;
     if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
       const context = { trigger: 'auto' };
       const snapResult = createGitSnapshot(projectDir, cfg, { branchRef, context });
       if (snapResult.status === 'created') {
         changedFileCount = snapResult.changedCount != null ? snapResult.changedCount : 0;
+        changedFiles = snapResult.changedFiles;
         let msg = `Git snapshot ${snapResult.shortHash} (${snapResult.fileCount} files)`;
         if (snapResult.secretsExcluded) {
           msg += ` [secrets excluded: ${snapResult.secretsExcluded.join(', ')}]`;
@@ -272,7 +274,7 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
     }
 
     // V4: Record change event and check for anomalies (after snapshot, using accurate count)
-    recordChange(tracker, changedFileCount);
+    recordChange(tracker, changedFileCount, changedFiles);
     const anomalyResult = checkAnomaly(tracker);
     if (anomalyResult.anomaly && anomalyResult.alert && !anomalyResult.suppressed) {
       saveAlert(projectDir, anomalyResult.alert);
@@ -283,7 +285,8 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
     if (cfg.backup_strategy === 'shadow' || cfg.backup_strategy === 'both') {
       const shadowResult = createShadowCopy(projectDir, cfg, { backupDir });
       if (shadowResult.status === 'created') {
-        logger.log(`Shadow copy ${shadowResult.timestamp} (${shadowResult.fileCount} files)`);
+        const linkInfo = shadowResult.linkedCount ? ` [${shadowResult.linkedCount} hard-linked]` : '';
+        logger.log(`Shadow copy ${shadowResult.timestamp} (${shadowResult.fileCount} files${linkInfo})`);
         if (pendingManifest) {
           saveManifest(backupDir, pendingManifest);
           pendingManifest = null;

package/references/lib/core/anomaly.js

@@ -84,6 +84,27 @@ function checkAnomaly(tracker) {
     return { anomaly: true, alert: lastAlert, suppressed: true };
   }
 
+  // Aggregate per-file details from recent events, deduplicated by path (latest wins)
+  const fileMap = new Map();
+  for (const e of recentEvents) {
+    if (Array.isArray(e.files)) {
+      for (const f of e.files) {
+        if (f && f.path) {
+          const existing = fileMap.get(f.path);
+          if (existing) {
+            existing.added = (existing.added || 0) + (f.added || 0);
+            existing.deleted = (existing.deleted || 0) + (f.deleted || 0);
+          } else {
+            fileMap.set(f.path, { path: f.path, action: f.action || 'modified', added: f.added || 0, deleted: f.deleted || 0 });
+          }
+        }
+      }
+    }
+  }
+  const alertFiles = [...fileMap.values()]
+    .sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted))
+    .slice(0, 50);
+
   const alert = {
     type: 'high_change_velocity',
     detectedAt: now,
@@ -93,6 +114,7 @@ function checkAnomaly(tracker) {
     threshold: tracker.config.filesPerWindow,
     expiresAt: new Date(now + 5 * 60 * 1000).toISOString(),
     recommendation: 'High volume of file changes detected. Consider reviewing recent modifications and creating a manual snapshot.',
+    files: alertFiles.length > 0 ? alertFiles : undefined,
   };
 
   tracker.alerts.push(alert);

package/references/lib/core/backups.js

@@ -398,4 +398,65 @@ function cleanGitRetention(branchRef, gitDirPath, cfg, cwd) {
   return { kept: keepCount, pruned: total - keepCount, mode, rebuilt: true };
 }
 
-module.exports = { listBackups, cleanShadowRetention, cleanGitRetention, parseShadowTimestamp };
+// ── Get backup file details ─────────────────────────────────────
+
+/**
+ * Get structured file-level changes for a specific git backup commit.
+ * Runs diff-tree --numstat + --name-status against parent (or ls-tree for root).
+ *
+ * @param {string} projectDir
+ * @param {string} commitHash - Full or short commit hash
+ * @returns {{ files: Array<{path: string, action: string, added: number, deleted: number}>, error?: string }}
+ */
+function getBackupFiles(projectDir, commitHash) {
+  if (!isGitRepo(projectDir)) {
+    return { files: [], error: 'not a git repository' };
+  }
+
+  const resolved = git(['rev-parse', '--verify', commitHash], { cwd: projectDir, allowFail: true });
+  if (!resolved) {
+    return { files: [], error: `cannot resolve commit: ${commitHash}` };
+  }
+
+  const parentCheck = git(['rev-parse', '--verify', `${resolved}^`], { cwd: projectDir, allowFail: true });
+
+  if (!parentCheck) {
+    const lsOut = git(['ls-tree', '--name-only', '-r', resolved], { cwd: projectDir, allowFail: true });
+    if (!lsOut) return { files: [] };
+    return {
+      files: lsOut.split('\n').filter(Boolean).map(f => ({ path: f, action: 'added', added: 0, deleted: 0 })),
+    };
+  }
+
+  const nameStatusOut = git(['diff-tree', '--no-commit-id', '--name-status', '-r', `${resolved}^`, resolved], { cwd: projectDir, allowFail: true });
+  const numstatOut = git(['diff-tree', '--no-commit-id', '--numstat', '-r', `${resolved}^`, resolved], { cwd: projectDir, allowFail: true });
+
+  const stats = {};
+  if (numstatOut) {
+    for (const line of numstatOut.split('\n').filter(Boolean)) {
+      const [add, del, ...nameParts] = line.split('\t');
+      const fname = nameParts.join('\t');
+      stats[fname] = { added: add === '-' ? 0 : parseInt(add, 10), deleted: del === '-' ? 0 : parseInt(del, 10) };
+    }
+  }
+
+  const ACTION_MAP = { M: 'modified', A: 'added', D: 'deleted' };
+  const files = [];
+  if (nameStatusOut) {
+    for (const line of nameStatusOut.split('\n').filter(Boolean)) {
+      const tab = line.indexOf('\t');
+      if (tab < 0) continue;
+      const code = line.substring(0, tab).trim();
+      const filePart = line.substring(tab + 1);
+      const action = code.startsWith('R') ? 'renamed' : (ACTION_MAP[code] || 'modified');
+      const fileName = filePart.split('\t').pop();
+      const s = stats[fileName] || { added: 0, deleted: 0 };
+      files.push({ path: fileName, action, added: s.added, deleted: s.deleted });
+    }
+  }
+
+  files.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
+  return { files };
+}
+
+module.exports = { listBackups, getBackupFiles, cleanShadowRetention, cleanGitRetention, parseShadowTimestamp };

package/references/lib/core/snapshot.js

@@ -141,6 +141,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
     // Build incremental summary from actual tree diff (not working-dir status)
     let changedCount;
     let incrementalSummary;
+    let changedFiles;
     if (parentTree) {
       const diffOut = git(['diff-tree', '--no-commit-id', '--name-status', '-r', parentTree, newTree], { cwd, allowFail: true });
       if (diffOut) {
@@ -166,14 +167,25 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
           for (const line of numstatOut.split('\n').filter(Boolean)) {
             const [add, del, ...nameParts] = line.split('\t');
             const fname = nameParts.join('\t');
-            if (add !== '-') stats[fname] = `+${add} -${del}`;
+            stats[fname] = { added: add === '-' ? 0 : parseInt(add, 10), deleted: del === '-' ? 0 : parseInt(del, 10) };
           }
         }
 
+        // Build structured changedFiles array
+        changedFiles = [];
+        const ACTION_MAP = { M: 'modified', A: 'added', D: 'deleted', R: 'renamed' };
+        for (const [key, arr] of Object.entries(groups)) {
+          for (const f of arr) {
+            const s = stats[f] || { added: 0, deleted: 0 };
+            changedFiles.push({ path: f, action: ACTION_MAP[key], added: s.added, deleted: s.deleted });
+          }
+        }
+        changedFiles.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
+
         function fmtFiles(arr) {
           return arr.slice(0, 5).map(f => {
             const s = stats[f];
-            return s ? `${f} (${s})` : f;
+            return s ? `${f} (+${s.added} -${s.deleted})` : f;
           }).join(', ');
         }
 
@@ -191,6 +203,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
         changedCount = files.length;
         const sample = files.slice(0, 5).join(', ');
         incrementalSummary = `Added ${files.length}: ${sample}${files.length > 5 ? ', ...' : ''}`;
+        changedFiles = files.map(f => ({ path: f, action: 'added', added: 0, deleted: 0 }));
       }
     }
 
@@ -226,6 +239,7 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
       shortHash: commitHash.substring(0, 7),
       fileCount,
       changedCount,
+      changedFiles,
       incrementalSummary,
       secretsExcluded: secretsExcluded.length > 0 ? secretsExcluded : undefined,
     };
@@ -248,6 +262,20 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
  * @param {string} [opts.backupDir] - Override backup directory (default: projectDir/.cursor-guard-backup)
  * @returns {{ status: 'created'|'empty'|'error', timestamp?: string, fileCount?: number, snapshotDir?: string, error?: string }}
  */
+function findPreviousSnapshot(backupDir) {
+  try {
+    const entries = fs.readdirSync(backupDir)
+      .filter(e => /^\d{8}_\d{6}/.test(e))
+      .sort()
+      .reverse();
+    for (const e of entries) {
+      const full = path.join(backupDir, e);
+      if (fs.statSync(full).isDirectory()) return full;
+    }
+  } catch { /* no previous snapshots */ }
+  return null;
+}
+
 function createShadowCopy(projectDir, cfg, opts = {}) {
   const backupDir = opts.backupDir || path.join(projectDir, '.cursor-guard-backup');
   let ts = formatTimestamp(new Date());
@@ -264,15 +292,37 @@ function createShadowCopy(projectDir, cfg, opts = {}) {
     }
     fs.mkdirSync(snapDir, { recursive: true });
 
+    const prevSnapDir = findPreviousSnapshot(backupDir);
+
     const allFiles = walkDir(projectDir, projectDir);
     const files = filterFiles(allFiles, cfg);
 
     let copied = 0;
+    let linked = 0;
     for (const f of files) {
       const dest = path.join(snapDir, f.rel);
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       try {
-        fs.copyFileSync(f.full, dest);
+        let didLink = false;
+        if (prevSnapDir) {
+          const prevFile = path.join(prevSnapDir, f.rel);
+          try {
+            const srcStat = fs.statSync(f.full);
+            const prevStat = fs.statSync(prevFile);
+            if (srcStat.size === prevStat.size && Math.abs(srcStat.mtimeMs - prevStat.mtimeMs) < 1) {
+              fs.linkSync(prevFile, dest);
+              didLink = true;
+              linked++;
+            }
+          } catch { /* prev file missing or stat error — fall through to copy */ }
+        }
+        if (!didLink) {
+          fs.copyFileSync(f.full, dest);
+          try {
+            const srcStat = fs.statSync(f.full);
+            fs.utimesSync(dest, srcStat.atime, srcStat.mtime);
+          } catch { /* non-critical: mtime preservation failed */ }
+        }
         copied++;
       } catch { /* skip unreadable */ }
     }
@@ -282,7 +332,7 @@ function createShadowCopy(projectDir, cfg, opts = {}) {
       return { status: 'empty', timestamp: ts };
     }
 
-    return { status: 'created', timestamp: ts, fileCount: copied, snapshotDir: snapDir };
+    return { status: 'created', timestamp: ts, fileCount: copied, linkedCount: linked, snapshotDir: snapDir };
   } catch (e) {
     return { status: 'error', error: e.message };
   }

package/references/lib/utils.js

@@ -137,6 +137,7 @@ const DEFAULT_CONFIG = {
   git_retention: { enabled: false, mode: 'count', days: 30, max_count: 200 },
   proactive_alert: true,
   alert_thresholds: { files_per_window: 20, window_seconds: 10, cooldown_seconds: 60 },
+  always_watch: false,
 };
 
 function loadConfig(projectDir) {
@@ -221,6 +222,11 @@ function loadConfig(projectDir) {
       if (typeof raw.alert_thresholds.cooldown_seconds === 'number' && raw.alert_thresholds.cooldown_seconds > 0)
         cfg.alert_thresholds.cooldown_seconds = raw.alert_thresholds.cooldown_seconds;
     }
+    if (raw.always_watch === true) {
+      cfg.always_watch = true;
+    } else if (raw.always_watch !== undefined && raw.always_watch !== false) {
+      warnings.push(`always_watch should be a boolean, got ${JSON.stringify(raw.always_watch)} — using default (false)`);
+    }
     return { cfg, loaded: true, error: null, warnings };
   } catch (e) {
     return { cfg, loaded: false, error: e.message };

package/references/mcp/server.js

@@ -15,10 +15,35 @@ const { getBackupStatus } = require('../lib/core/status');
 const { getDashboard } = require('../lib/core/dashboard');
 const { loadActiveAlert } = require('../lib/core/anomaly');
 
-const { gitDir: getGitDir } = require('../lib/utils');
+const { loadConfig, gitDir: getGitDir } = require('../lib/utils');
 
 const pkg = require('../../package.json');
 
+// ── Auto-watch manager for always_watch mode ─────────────────
+
+const watchedProjects = new Map();
+
+function ensureWatcher(projectPath) {
+  if (watchedProjects.has(projectPath)) return;
+  const { cfg, loaded } = loadConfig(projectPath);
+  if (!loaded || !cfg.always_watch) return;
+  if (isWatcherRunning(projectPath)) {
+    watchedProjects.set(projectPath, { pid: null, external: true });
+    return;
+  }
+  try {
+    const { spawn } = require('child_process');
+    const watcherScript = path.join(__dirname, '..', 'bin', 'cursor-guard-backup.js');
+    const child = spawn(process.execPath, [watcherScript, '--path', projectPath], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.unref();
+    watchedProjects.set(projectPath, { pid: child.pid, external: false });
+  } catch { /* spawn failed — non-fatal */ }
+}
+
 // ── Alert injection helper ──────────────────────────────────────
 
 function injectAlert(projectPath, result) {
@@ -78,6 +103,7 @@ server.tool(
   },
   async ({ path: projectPath }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
     const result = injectAlert(resolved, runDiagnostics(resolved));
     injectWatcherWarning(resolved, result);
     return {
@@ -102,6 +128,7 @@ server.tool(
   },
   async ({ path: projectPath, file, before, limit }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
     const result = injectAlert(resolved, listBackups(resolved, { file, before, limit }));
     return {
       content: [{
@@ -128,7 +155,7 @@ server.tool(
   },
   async ({ path: projectPath, strategy, message, scope, intent, agent, session }) => {
     const resolved = path.resolve(projectPath);
-    const { loadConfig } = require('../lib/utils');
+    ensureWatcher(resolved);
     const { cfg } = loadConfig(resolved);
 
     if (scope === 'all') {
@@ -182,6 +209,7 @@ server.tool(
   },
   async ({ path: projectPath, file, source, preserve_current }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
     const result = injectAlert(resolved, restoreFile(resolved, file, source, {
       preserveCurrent: preserve_current,
     }));
@@ -209,6 +237,7 @@ server.tool(
   },
   async ({ path: projectPath, source, preview, preserve_current, clean_untracked }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
 
     if (preview !== false) {
       const result = injectAlert(resolved, previewProjectRestore(resolved, source));
@@ -235,6 +264,7 @@ server.tool(
   },
   async ({ path: projectPath, dry_run }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
     const result = injectAlert(resolved, runFixes(resolved, { dryRun: !!dry_run }));
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
@@ -250,6 +280,7 @@ server.tool(
   },
   async ({ path: projectPath }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
     const result = injectAlert(resolved, getBackupStatus(resolved));
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
@@ -265,6 +296,7 @@ server.tool(
   },
   async ({ path: projectPath }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
     const result = injectAlert(resolved, getDashboard(resolved));
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
@@ -280,6 +312,7 @@ server.tool(
   },
   async ({ path: projectPath }) => {
     const resolved = path.resolve(projectPath);
+    ensureWatcher(resolved);
     const alert = loadActiveAlert(resolved);
     const result = alert
       ? { active: true, alert }