cursor-guard 4.5.4 → 4.5.6

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.5.4`（V4 最终版）  
-> **文档状态**：`V2` ~ `V4.5.4` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.5.6`（V4 最终版）  
+> **文档状态**：`V2` ~ `V4.5.6` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -462,6 +462,7 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | V4.5.2 | **告警结构化文件列表**：见下方详细说明 | ✅ |
 | V4.5.3 | **告警历史 UX 优化 + 备份结构化文件表格**：见下方详细说明 | ✅ |
 | V4.5.4 | **Shadow 硬链接增量优化 + always_watch 强保护模式**：见下方详细说明 | ✅ |
+| V4.5.6 | **Bug 修复 + 告警 UX + init 优化**：见下方详细说明 | ✅ |
 
 #### V4.4.1 详细内容
 
@@ -619,6 +620,38 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 
 > 这个特性直接填补了 V4 最大的架构缺口——"Watcher 停止 = 裸奔"。详见下方"V4 遗留的架构缺口"中该条目已标记为 **已解决**。
 
+#### V4.5.6 详细内容
+
+**Bug 修复**：
+
+| 问题 | 严重度 | 根因 | 修复 |
+|------|--------|------|------|
+| Shadow hard-link 永远为 0 | 中 | `createShadowCopy` 中 `fs.mkdirSync(snapDir)` 在 `findPreviousSnapshot(backupDir)` 之前执行。新创建的空目录时间戳最新，被当作"上一个快照"返回，导致硬链接永远找不到文件 | 调换两行顺序：先 `findPreviousSnapshot`，再 `mkdirSync` |
+| changedFiles 包含 ignore 路径 | 低 | `createGitSnapshot` 的 `diff-tree` 解析未按 `cfg.ignore` 过滤，`.cursor/` 等被忽略路径的文件混入告警的 files 数组和 changedCount | 在 diff-tree 解析循环中增加 `matchesAny(cfg.ignore, fileName)` 过滤；initial snapshot 的 `ls-tree` 列表同样过滤 |
+
+**告警 UX 优化**：
+
+| 改进 | 说明 |
+|------|------|
+| 告警详情增加文件类型摘要 | 活跃告警和历史告警均显示 "新增 N · 修改 N · 删除 N" 分类统计（`alertFileBreakdown` 辅助函数） |
+| 活跃告警增加建议操作 | 告警卡片底部显示 "建议检查近期变更，并考虑手动创建快照" 提示文字 |
+| i18n 补全 | 新增 `alert.breakdown`、`alert.suggestion` 双语 key |
+
+**Dashboard UX 优化**：
+
+| 改进 | 说明 |
+|------|------|
+| 文件详情弹出框（Modal） | 告警的"展开文件详情"改为全屏居中 Modal 弹窗，替代原本卡片内联展开（太小看不清）。Modal 支持排序、可滚动、720px 宽 |
+| 每个文件可复制恢复命令 | Modal 和 Drawer 的文件表格中，每行增加"复制命令"按钮，一键生成 `restore_file({ path, file, source })` MCP 命令 |
+| 备份表补全操作意图 | 备份表 summary 列：有 intent 时显示 "操作意图: xxx"（蓝色标签），无 intent 时显示 trigger 类型（自动/手动/恢复前）灰色文字 |
+
+**工具链优化**：
+
+| 改进 | 说明 |
+|------|------|
+| `cursor-guard-init` 自动创建配置 | init 流程新增 Step 4/5：若 `.cursor-guard.json` 不存在，自动从 `cursor-guard.example.json` 复制为项目根默认配置。升级场景下保留现有配置 |
+| `backup_interval_seconds` 兼容别名 | `loadConfig` 支持 `backup_interval_seconds` 作为 `auto_backup_interval_seconds` 的别名（带 deprecation 警告） |
+
 #### V4.5.x 新增配置参考
 
 | 字段 | 类型 | 默认值 | 引入版本 | 说明 |
@@ -663,8 +696,9 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 
 ### 进入 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 机制已相对成熟
 
@@ -674,10 +708,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 无法做到的，需要架构升级 |
 
 ### 为什么需要这一步
 
@@ -698,29 +734,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 + 文件路径意图绑定
 
@@ -789,8 +831,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
@@ -938,7 +987,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 一致（无退化）
@@ -946,7 +996,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.4",
+  "version": "4.5.6",
   "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/bin/cursor-guard-init.js

@@ -64,7 +64,7 @@ if (fs.existsSync(configPath)) {
 }
 
 // Step 1: Copy skill files (excluding node_modules and .git)
-console.log('  [1/4] Copying skill files...');
+console.log('  [1/5] Copying skill files...');
 if (fs.existsSync(skillTarget)) {
   fs.rmSync(skillTarget, { recursive: true, force: true });
 }
@@ -72,7 +72,7 @@ copyRecursive(skillSource, skillTarget);
 console.log('        Done.');
 
 // Step 2: Install MCP dependencies in skill directory
-console.log('  [2/4] Installing MCP dependencies...');
+console.log('  [2/5] Installing MCP dependencies...');
 try {
   const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
   execFileSync(npmCmd, ['install', '--omit=dev', '--ignore-scripts'], {
@@ -86,7 +86,7 @@ try {
 }
 
 // Step 3: Add .gitignore entries for skill node_modules
-console.log('  [3/4] Updating .gitignore...');
+console.log('  [3/5] Updating .gitignore...');
 const gitignorePath = path.join(projectDir, '.gitignore');
 const entries = ['node_modules/', '.cursor/skills/**/node_modules/'];
 let gitignoreUpdated = false;
@@ -106,8 +106,22 @@ if (!isGlobal) {
   console.log('        Skipped (global install, not inside a project).');
 }
 
-// Step 4: Summary
-console.log('  [4/4] Verifying...');
+// Step 4: Create default config if missing
+console.log('  [4/5] Checking .cursor-guard.json...');
+if (!fs.existsSync(configPath)) {
+  const examplePath = path.join(skillTarget, 'references', 'cursor-guard.example.json');
+  if (fs.existsSync(examplePath)) {
+    fs.copyFileSync(examplePath, configPath);
+    console.log('        Created .cursor-guard.json with default settings.');
+  } else {
+    console.log('        Warning: example config not found, skipping.');
+  }
+} else {
+  console.log('        Already exists — preserved.');
+}
+
+// Step 5: Summary
+console.log('  [5/5] Verifying...');
 const serverExists = fs.existsSync(path.join(skillTarget, 'references', 'mcp', 'server.js'));
 const sdkExists = fs.existsSync(path.join(skillTarget, 'node_modules', '@modelcontextprotocol', 'sdk'));
 const skillMdExists = fs.existsSync(path.join(skillTarget, 'SKILL.md'));
@@ -130,8 +144,7 @@ console.log('  If MCP was already configured, restart Cursor (or Ctrl+Shift+P ->
 console.log('     "Developer: Reload Window") to load the updated MCP server.\n');
 console.log('  Next steps:');
 console.log('  1. The skill activates automatically in Cursor Agent conversations.');
-console.log('  2. (Optional) Copy example config to project root:');
-console.log(`     cp "${path.join(skillTarget, 'references', 'cursor-guard.example.json')}" .cursor-guard.json`);
+console.log('  2. (Optional) Edit .cursor-guard.json to customize protect/ignore patterns.');
 console.log('  3. (Optional) Enable MCP — add to .cursor/mcp.json:');
 console.log(`     { "mcpServers": { "cursor-guard": { "command": "node", "args": ["${path.join(skillTarget, 'references', 'mcp', 'server.js').replace(/\\/g, '/')}"] } } }`);
 console.log('  4. (Optional) Start auto-backup:');

package/references/dashboard/public/app.js

@@ -56,6 +56,13 @@ const I18N = {
     'alert.action.added':    'Added',
     'alert.action.deleted':  'Deleted',
     'alert.action.renamed':  'Renamed',
+    'alert.breakdown':       '{added} added, {modified} modified, {deleted} deleted',
+    'alert.suggestion':      'Check recent changes and consider creating a manual snapshot',
+    'alert.viewFiles':       'View file details ({n} files)',
+    'modal.alertFiles':      'Alert File Details',
+    'modal.col.restore':     'Restore',
+    'modal.copyRestore':     'Copy cmd',
+    'modal.copied':          'Copied!',
 
     'backups.gitCommits':       'Git Commits',
     'backups.shadowSnapshots':  'Shadow Snapshots',
@@ -264,6 +271,13 @@ const I18N = {
     'alert.action.added':    '新增',
     'alert.action.deleted':  '删除',
     'alert.action.renamed':  '重命名',
+    'alert.breakdown':       '新增 {added} · 修改 {modified} · 删除 {deleted}',
+    'alert.suggestion':      '建议检查近期变更，并考虑手动创建快照',
+    'alert.viewFiles':       '查看文件详情（{n} 个文件）',
+    'modal.alertFiles':      '告警文件详情',
+    'modal.col.restore':     '恢复',
+    'modal.copyRestore':     '复制命令',
+    'modal.copied':          '已复制！',
 
     'backups.gitCommits':       'Git 提交数',
     'backups.shadowSnapshots':  '影子快照',
@@ -846,19 +860,32 @@ function renderWatcherCard(watcher) {
   `;
 }
 
+function alertFileBreakdown(files) {
+  if (!Array.isArray(files) || files.length === 0) return '';
+  let added = 0, modified = 0, deleted = 0;
+  for (const f of files) {
+    if (f.action === 'added') added++;
+    else if (f.action === 'deleted') deleted++;
+    else modified++;
+  }
+  return t('alert.breakdown', { added, modified, deleted });
+}
+
 function renderAlertCard(alerts) {
   const el = $('#card-alert');
   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>
+      const rows = state.alertHistory.slice(-5).reverse().map(h => {
+        const breakdown = alertFileBreakdown(h.files);
+        return `<div class="alert-history-row text-sm text-muted">
+          <span class="alert-history-time">${esc(formatTime(h.timestamp))}</span>
           <span>${t('alert.detail', { count: h.fileCount, window: h.windowSeconds, threshold: h.threshold })}</span>
+          ${breakdown ? `<span class="alert-history-breakdown">${esc(breakdown)}</span>` : ''}
           <span class="badge badge-expired">${t('alert.expired')}</span>
-        </div>`
-      ).join('');
+        </div>`;
+      }).join('');
       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>
@@ -893,25 +920,9 @@ function renderAlertCard(alerts) {
   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>
+        <button class="alert-files-toggle" data-alert-files-modal>${t('alert.viewFiles', { n: files.length })}</button>
       </div>
     `;
   }
@@ -923,6 +934,8 @@ function renderAlertCard(alerts) {
       <div class="alert-detail-row"><span class="alert-detail-label">${t('alert.triggered')}</span><span>${esc(triggeredAt)}</span></div>
       <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>
+      ${alertFileBreakdown(files) ? `<div class="alert-detail-row alert-breakdown text-sm">${esc(alertFileBreakdown(files))}</div>` : ''}
+      <div class="alert-detail-row alert-suggestion text-sm text-muted">${t('alert.suggestion')}</div>
     </div>
     ${filesHtml}
   `;
@@ -1046,11 +1059,14 @@ function formatSummaryCell(b) {
     line2 = `<div class="summary-restore-ctx">${label}<span class="text-mono">${esc(b.from)}</span> → <span class="text-mono">${esc(b.restoreTo)}</span></div>`;
   } else if (b.intent) {
     const intentShort = b.intent.length > 70 ? b.intent.substring(0, 67) + '...' : b.intent;
-    line2 = `<div class="summary-intent">${esc(intentShort)}</div>`;
+    line2 = `<div class="summary-intent"><span class="summary-intent-label">${t('drawer.field.intent')}:</span> ${esc(intentShort)}</div>`;
   } else if (b.message && !b.message.startsWith('guard:')) {
     const msgShort = b.message.length > 70 ? b.message.substring(0, 67) + '...' : b.message;
     line2 = `<div class="summary-message">${esc(msgShort)}</div>`;
   }
+  if (b.trigger && !line2) {
+    line2 = `<div class="summary-trigger text-sm text-muted">${t('trigger.' + b.trigger)}</div>`;
+  }
 
   let line3 = '';
   if (b.summary) {
@@ -1182,6 +1198,67 @@ function renderSectionError(elementId, msg) {
   el.innerHTML = `<div class="error-panel"><div class="error-icon">⚠</div><p>${esc(msg || t('error.sectionFailed'))}</p></div>`;
 }
 
+/* ── File Detail Modal ────────────────────────────────────── */
+
+function openFileModal(title, files, projectPath, commitHash) {
+  $('#file-modal-title').textContent = title;
+  const body = $('#file-modal-body');
+  let sortKey = 'changes';
+  const render = () => {
+    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 => {
+      const restoreCmd = commitHash
+        ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${commitHash}" })`
+        : '';
+      return `<tr>
+        <td class="text-mono modal-file-path" title="${esc(f.path)}">${esc(f.path)}</td>
+        <td>${formatFileActionBadge(f.action)}</td>
+        <td class="text-mono modal-file-changes">+${f.added || 0} -${f.deleted || 0}</td>
+        ${commitHash ? `<td><button class="modal-restore-btn" data-restore-cmd="${esc(restoreCmd)}">${t('modal.copyRestore')}</button></td>` : ''}
+      </tr>`;
+    }).join('');
+
+    body.innerHTML = `<table>
+      <thead><tr>
+        <th data-msort="path">${t('alert.col.file')} ↕</th>
+        <th data-msort="action">${t('alert.col.action')} ↕</th>
+        <th data-msort="changes">${t('alert.col.changes')} ↕</th>
+        ${commitHash ? `<th>${t('modal.col.restore')}</th>` : ''}
+      </tr></thead>
+      <tbody>${rows}</tbody>
+    </table>`;
+  };
+  render();
+
+  body.addEventListener('click', (e) => {
+    const th = e.target.closest('[data-msort]');
+    if (th) {
+      sortKey = th.dataset.msort;
+      render();
+      return;
+    }
+    const btn = e.target.closest('[data-restore-cmd]');
+    if (btn) {
+      copyText(btn.dataset.restoreCmd);
+      btn.textContent = t('modal.copied');
+      btn.classList.add('copied');
+      setTimeout(() => { btn.textContent = t('modal.copyRestore'); btn.classList.remove('copied'); }, 1500);
+    }
+  });
+
+  $('#file-modal-overlay').classList.add('active');
+  document.body.style.overflow = 'hidden';
+}
+
+function closeFileModal() {
+  $('#file-modal-overlay').classList.remove('active');
+  document.body.style.overflow = state.drawerOpen ? 'hidden' : '';
+}
+
 /* ── Drawers ──────────────────────────────────────────────── */
 
 function openDrawer(name) {
@@ -1199,19 +1276,27 @@ function closeDrawer() {
   state.drawerOpen = null;
 }
 
-function renderDrawerFilesTable(files, sortKey) {
+function renderDrawerFilesTable(files, sortKey, commitHash, projectPath) {
   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('');
+  const hasRestore = !!commitHash;
+  const rows = sorted.map(f => {
+    const cmd = hasRestore ? `restore_file({ path: "${projectPath || ''}", file: "${f.path}", source: "${commitHash}" })` : '';
+    return `<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>
+      ${hasRestore ? `<td><button class="modal-restore-btn" data-restore-cmd="${esc(cmd)}">${t('modal.copyRestore')}</button></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>
+      ${hasRestore ? `<th>${t('modal.col.restore')}</th>` : ''}
     </tr></thead>
     <tbody>${rows}</tbody>
   </table>`;
@@ -1292,28 +1377,40 @@ function openRestoreDrawer(backup) {
     wrap.classList.toggle('hidden');
   });
 
+  const projPath = backup.path || state.pageData?.status?.config?.path || '';
+
   // Lazy-load full file list for summary section
   if (backup.summary && isGit && hash) {
     let currentFiles = [];
     let currentSort = 'changes';
+    const setupContainer = (container) => {
+      container.innerHTML = renderDrawerFilesTable(currentFiles, currentSort, hash, projPath);
+      container.addEventListener('click', (e) => {
+        const th = e.target.closest('[data-sort]');
+        if (th) {
+          currentSort = th.dataset.sort;
+          container.innerHTML = renderDrawerFilesTable(currentFiles, currentSort, hash, projPath);
+          return;
+        }
+        const restoreBtn = e.target.closest('[data-restore-cmd]');
+        if (restoreBtn) {
+          copyText(restoreBtn.dataset.restoreCmd);
+          restoreBtn.textContent = t('modal.copied');
+          restoreBtn.classList.add('copied');
+          setTimeout(() => { restoreBtn.textContent = t('modal.copyRestore'); restoreBtn.classList.remove('copied'); }, 1500);
+        }
+      });
+    };
     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);
-        });
-      }
+      if (container) setupContainer(container);
     });
   } 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');
+      container.innerHTML = renderDrawerFilesTable(fallback, 'changes', hash, projPath);
     } 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>`;
@@ -1432,7 +1529,7 @@ function setupEvents() {
     if (backup) openRestoreDrawer(backup);
   });
 
-  // Alert history + files toggle (event delegation)
+  // Alert history toggle + file modal (event delegation)
   $('#card-alert').addEventListener('click', (e) => {
     const historyToggle = e.target.closest('[data-alert-history-toggle]');
     if (historyToggle) {
@@ -1441,14 +1538,16 @@ function setupEvents() {
       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');
+    const modalBtn = e.target.closest('[data-alert-files-modal]');
+    if (modalBtn) {
+      const alerts = state.pageData?.alerts;
+      const files = alerts?.latest?.files || [];
+      if (files.length > 0) {
+        const proj = state.pageData?.status?.config?.path || '';
+        openFileModal(t('modal.alertFiles'), files, proj, '');
+      }
+      return;
+    }
   });
 
   // Diagnostics summary click
@@ -1467,8 +1566,17 @@ function setupEvents() {
   document.querySelectorAll('[data-action="close-drawer"]').forEach(btn => {
     btn.addEventListener('click', closeDrawer);
   });
+
+  // Close modal
+  $('#file-modal-overlay').addEventListener('click', (e) => {
+    if (e.target === $('#file-modal-overlay')) closeFileModal();
+  });
+  document.querySelectorAll('[data-action="close-modal"]').forEach(btn => {
+    btn.addEventListener('click', closeFileModal);
+  });
+
   document.addEventListener('keydown', (e) => {
-    if (e.key === 'Escape') closeDrawer();
+    if (e.key === 'Escape') { closeFileModal(); closeDrawer(); }
   });
 }
 

package/references/dashboard/public/index.html

@@ -75,6 +75,17 @@
 
   </main>
 
+  <!-- ── File Detail Modal ──────────────────────────────────── -->
+  <div id="file-modal-overlay" class="modal-overlay">
+    <div id="file-modal" class="file-modal">
+      <div class="file-modal-header">
+        <h3 id="file-modal-title"></h3>
+        <button class="drawer-close" data-action="close-modal">&times;</button>
+      </div>
+      <div id="file-modal-body" class="file-modal-body"></div>
+    </div>
+  </div>
+
   <!-- ── Drawer Overlay ───────────────────────────────────── -->
   <div id="drawer-overlay" class="drawer-overlay"></div>
 

package/references/dashboard/public/style.css

@@ -349,6 +349,14 @@ main {
   max-width: 400px;
   line-height: 1.4;
 }
+.summary-intent-label {
+  font-weight: 600;
+  opacity: 0.7;
+}
+.summary-trigger {
+  font-size: 11px;
+  padding: 2px 0;
+}
 .summary-restore-ctx {
   font-size: 12px;
   color: var(--amber);
@@ -997,6 +1005,22 @@ main {
   border-left: 3px solid var(--yellow);
 }
 
+.alert-breakdown {
+  color: var(--text-secondary);
+  font-weight: 500;
+  padding: 2px 12px;
+}
+.alert-suggestion {
+  padding: 4px 12px;
+  font-style: italic;
+}
+.alert-history-breakdown {
+  display: block;
+  font-size: 10px;
+  color: var(--text-tertiary);
+  margin-top: 1px;
+}
+
 .alert-history-toggle-wrap {
   margin-top: 8px;
 }
@@ -1236,6 +1260,103 @@ main {
   color: var(--text-heading);
 }
 
+/* ── File Detail Modal ────────────────────────────────────── */
+
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.55);
+  z-index: 2000;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  backdrop-filter: blur(2px);
+}
+.modal-overlay.active {
+  display: flex;
+}
+.file-modal {
+  background: var(--card-bg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  width: 90vw;
+  max-width: 720px;
+  max-height: 80vh;
+  display: flex;
+  flex-direction: column;
+  box-shadow: 0 16px 48px rgba(0, 0, 0, 0.3);
+}
+.file-modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 14px 20px;
+  border-bottom: 1px solid var(--border);
+}
+.file-modal-header h3 {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 600;
+}
+.file-modal-body {
+  padding: 16px 20px;
+  overflow-y: auto;
+  flex: 1;
+}
+.file-modal-body table {
+  width: 100%;
+  border-collapse: collapse;
+}
+.file-modal-body th,
+.file-modal-body td {
+  padding: 6px 10px;
+  text-align: left;
+  border-bottom: 1px solid var(--border);
+  font-size: 12px;
+}
+.file-modal-body th {
+  font-weight: 600;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.3px;
+  color: var(--text-secondary);
+  cursor: pointer;
+  user-select: none;
+}
+.file-modal-body th:hover {
+  color: var(--accent);
+}
+.modal-file-path {
+  max-width: 340px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.modal-file-changes {
+  white-space: nowrap;
+}
+.modal-restore-btn {
+  padding: 2px 8px;
+  font-size: 10px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg);
+  color: var(--text-secondary);
+  cursor: pointer;
+  white-space: nowrap;
+  transition: all 0.15s;
+}
+.modal-restore-btn:hover {
+  background: var(--accent);
+  color: #fff;
+  border-color: var(--accent);
+}
+.modal-restore-btn.copied {
+  background: var(--green);
+  color: #fff;
+  border-color: var(--green);
+}
+
 /* ── Responsive ───────────────────────────────────────────── */
 
 @media (max-width: 768px) {

package/references/lib/core/snapshot.js

@@ -146,7 +146,6 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
       const diffOut = git(['diff-tree', '--no-commit-id', '--name-status', '-r', parentTree, newTree], { cwd, allowFail: true });
       if (diffOut) {
         const diffLines = diffOut.split('\n').filter(Boolean);
-        changedCount = diffLines.length;
         const groups = { M: [], A: [], D: [], R: [] };
         for (const line of diffLines) {
           const tab = line.indexOf('\t');
@@ -158,8 +157,10 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
             : code === 'A' ? 'A'
             : 'M';
           const fileName = filePart.split('\t').pop();
+          if (matchesAny(cfg.ignore, fileName) || matchesAny(cfg.ignore, path.basename(fileName))) continue;
           groups[key].push(fileName);
         }
+        changedCount = Object.values(groups).reduce((sum, arr) => sum + arr.length, 0);
 
         const numstatOut = git(['diff-tree', '--no-commit-id', '--numstat', '-r', parentTree, newTree], { cwd, allowFail: true });
         const stats = {};
@@ -199,7 +200,8 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
     } else {
       const lsInitial = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
       if (lsInitial) {
-        const files = lsInitial.split('\n').filter(Boolean);
+        const files = lsInitial.split('\n').filter(Boolean)
+          .filter(f => !matchesAny(cfg.ignore, f) && !matchesAny(cfg.ignore, path.basename(f)));
         changedCount = files.length;
         const sample = files.slice(0, 5).join(', ');
         incrementalSummary = `Added ${files.length}: ${sample}${files.length > 5 ? ', ...' : ''}`;
@@ -290,10 +292,10 @@ function createShadowCopy(projectDir, cfg, opts = {}) {
         snapDir = path.join(backupDir, ts);
       }
     }
-    fs.mkdirSync(snapDir, { recursive: true });
-
     const prevSnapDir = findPreviousSnapshot(backupDir);
 
+    fs.mkdirSync(snapDir, { recursive: true });
+
     const allFiles = walkDir(projectDir, projectDir);
     const files = filterFiles(allFiles, cfg);
 

package/references/lib/utils.js

@@ -177,7 +177,12 @@ function loadConfig(projectDir) {
         warnings.push(`Unknown backup_strategy "${raw.backup_strategy}", using default "${cfg.backup_strategy}"`);
       }
     }
-    if (typeof raw.auto_backup_interval_seconds === 'number') cfg.auto_backup_interval_seconds = raw.auto_backup_interval_seconds;
+    if (typeof raw.auto_backup_interval_seconds === 'number') {
+      cfg.auto_backup_interval_seconds = raw.auto_backup_interval_seconds;
+    } else if (typeof raw.backup_interval_seconds === 'number') {
+      cfg.auto_backup_interval_seconds = raw.backup_interval_seconds;
+      warnings.push('backup_interval_seconds is a deprecated alias — please use auto_backup_interval_seconds');
+    }
     if (typeof raw.pre_restore_backup === 'string') {
       if (VALID_PRE_RESTORE.includes(raw.pre_restore_backup)) {
         cfg.pre_restore_backup = raw.pre_restore_backup;