cursor-guard 4.4.1 → 4.5.1

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.4.0`（V4 收官版）  
-> **文档状态**：`V2` ~ `V4.4.0` 已实施（含 V5 intent/audit 基础），`V5` 主体规划中
+> **当前版本**：`V4.5.1`（V4 最终版）  
+> **文档状态**：`V2` ~ `V4.5.1` 已完成交付（含 V5 intent/audit 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -20,7 +20,7 @@
 |---|---|---|---|
 | `V2` | 能用 | Skill + Script | "AI 弄丢代码能恢复" |
 | `V3` | 更稳 | + Core 抽取 + 可选 MCP | "恢复操作更标准、更省 token" |
-| `V4` | 更聪明 | + 主动检测 + 可观测 + Web 仪表盘 + Intent + 增量摘要 | "cursor-guard 会主动提醒你，能看到为什么备份、改了什么" ✅ |
+| `V4` | 更聪明 | + 主动检测 + 可观测 + Web 仪表盘 + Intent + 增量摘要 + 安全硬化 | "cursor-guard 会主动提醒你，能看到为什么备份、改了什么" ✅ |
 | `V5` | 成闭环 | + 变更控制层 | "AI 代码变更可预防、可追溯、可按事件恢复"（intent 基础已在 V4.3 落地） |
 | `V6` | 成标准 | + 开放协议 + 团队工作流 | "把 AI 代码变更安全做成跨工具标准" |
 | `V7` | 可证明 | + 可验证信任 + 治理层 | "能证明安全流程被执行了" |
@@ -457,6 +457,58 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | V4.3.4 | **运维加固**：`backup.log` 日志轮转（1MB / 3 文件）；watcher 单实例保护加固（锁文件时间戳 + 24h 超时）；`previewProjectRestore` 保护路径分组摘要（降低 token 消耗）；SKILL.md 硬规则 #15（升级后提交 skill 文件） | ✅ |
 | V4.3.5 | **Summary 准确性修复 + UI 优化**：备份摘要改用 `diff-tree` 增量对比（修复 porcelain 假摘要 bug）；仪表盘变更列三行堆叠布局；配色全面优化（背景层级 / 状态色 / 文字层级） | ✅ |
 | 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.4.1 详细内容
+
+**安全修复（2×P1 + 3×P2）**：
+
+| 级别 | 问题 | 修复 |
+|------|------|------|
+| P1 | `restoreFile` 接受目录 pathspec（`src`、`.cursor`）和项目根（`.`），单文件 API 能恢复整个目录或回滚受保护资产 | `validateRelativePath` 拦截 `.` 和空路径；`isToolPath` 匹配裸 `.cursor`；git 路径用 `cat-file -t` 验证必须是 blob（文件），tree（目录）直接拒绝；shadow 路径用 `statSync` 拦截目录 |
+| P1 | `restore_project` 对 HEAD 已删除的受保护文件不处理，旧快照会把它们复活 | 恢复前用 `ls-tree HEAD -- <path>` 检查存在性，HEAD 中不存在的路径用 `rmSync/unlinkSync` 清除 |
+| P2 | Git retention 重建链只保留 subject（`%s`），丢失 V4.3 审计 trailers | 改用 `%B`（完整 body + trailers），重建用 `fullBody` 传入 `commit-tree -m` |
+| P2 | Dashboard 仅绑定 127.0.0.1 但无 Host/token 防护，可被 DNS rebinding 读取 | 加 Host header 校验（`127.0.0.1`/`localhost`）+ per-process 随机 token 注入 index.html，API 请求必须携带 |
+| P2 | `doctor_fix` 初始化 Git 时 `git add -A` 会提交 `node_modules/` | 在 `git add -A` 前写入 `node_modules/` 和 `.cursor/skills/**/node_modules/` 到 `.gitignore` |
+
+**回归测试**：新增 3 条负例锁定 restore 防线（目录 pathspec / 受保护 .cursor / 项目根 `.`），总测试 143/143 全绿。
+
+**Dashboard UX**：
+- 骨架屏加载（shimmer 占位，消除白屏→弹出的突兀感）
+- 渐进渲染（`page-data?scope=` 按需返回，overview 先渲染，backups+doctor 并行加载）
+- 备份 summary 行级统计（`git diff-tree --numstat`，每文件 `(+N -M)`），分行显示
+- Summary 可见性提升（12px + secondary 颜色 + monospace 字体）
+- 去除变更列冗余 trigger badge（类型列已有）
+- Pre-restore 快照记录恢复方向（`From: <HEAD短hash>`、`Restore-To: <目标短hash>`、`File: <文件路径>`），表格琥珀色显示 `ab1b45d → f4029e9`
+
+**架构级防护缺口修复**：
+- MCP 工具注入 watcher 未运行警告（`_warning` 字段），AI 第一次调任何工具就能看到保护缺口
+- SKILL.md Hard Rule #1 升级："任何文件写入/删除前必须 snapshot"（之前仅要求"高风险操作前"）
+- SKILL.md 新增 Hard Rule #3a："必须检查 watcher 状态"——看到 `_warning` 必须告知用户
+
+#### V4.5.0 详细内容
+
+**Bug 修复**：
+
+| 问题 | 根因 | 修复 |
+|------|------|------|
+| 异常检测 `changedFileCount` 虚高 | `auto-backup.js` 用 `git status --porcelain`（对比 HEAD）计数，而非对比上一次备份的增量 | 改用 `createGitSnapshot` 返回的 `changedCount`（来自 `diff-tree`），异常检测和 Summary 共享同一数据源。移除了未使用的 `execFileSync` 和 `unquoteGitPath` 导入 |
+| 诊断锁文件状态判断不够智能 | `doctor.js` Lock file 检测只要存在就报 WARN，不区分 watcher 是否在运行 | 加入 PID 存活判断（`process.kill(pid, 0)`）：PID 在线 → PASS（`watcher running`）；PID 已死 → WARN（`stale lock file`）；无 PID → WARN（兜底）。前端 i18n 同步补全 `detail.lock_running` / `detail.lock_stale` / `detail.lock_exists` |
+
+**Dashboard 升级（10 项改进）**：
+
+| 优先级 | 改进 | 说明 |
+|--------|------|------|
+| 高 | 告警卡片补全 | 显示触发时间、过期倒计时（实时递减）、具体数字（N 文件 / N 秒 / 阈值 N） |
+| 高 | 告警历史 | 保留最近 20 条告警记录，即使过期也显示在卡片下方（最近 5 条） |
+| 中 | 文件搜索框 | 备份表格上方输入框，按文件名/意图/摘要实时过滤相关备份 |
+| 中 | 恢复命令复制 | 抽屉底部显示 `restore_project` 和 `restore_file` MCP 命令，一键复制 |
+| 低 | 筛选按钮计数 | "Git 自动备份 (12)" 而非仅 "Git 自动备份"；无数据的类型自动隐藏 |
+| 低 | Watcher 最后扫描 | 卡片增加 "最后扫描: 3s 前"，确认 watcher 实际在工作 |
+| 中 | 摘要展开/收起 | 变更摘要超过 2 行时自动折叠，显示 `+N more` 按钮点击展开；避免行过长截断，无需进抽屉即可看全 |
+| 修复 | `showLoading` 引用 | 项目切换时调用了不存在的 `showLoading()`，改为 `showSkeleton()` |
+| 优化 | i18n 补全 | 新增 14 个双语 key（告警详情、告警历史、文件搜索、恢复命令、扫描时间） |
 
 > **注**：V4.2 的 Web 仪表盘最初在 V4.0 规划中标记为"不做"，但用户需求明确后实施。事实证明只读仪表盘投入产出比合理，且不违反安全原则。
 
@@ -466,6 +518,18 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 - ~~不做 Web 仪表盘~~ → V4.2 已实施（只读、本地、零依赖）
 - 不做云端同步
 
+### V4 遗留的架构缺口（V5 接手）
+
+通过 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 的衡量标准
 
 - V4 的主动提醒功能误报率 < 10%
@@ -522,8 +586,101 @@ V5 不是"三个方向选一个"，而是把下面这条链路做完整：
 | `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 的所有核心事件和恢复路径都有测试覆盖 |
 
+### V5 核心设计：Embedded Watcher + 文件路径意图绑定
+
+#### 问题根因
+
+V4 的自动备份（auto-backup）和意图上下文（intent）分属两个独立进程：
+
+```
+MCP Server 进程（知道 intent）  ←——×——→  Watcher 进程（知道文件变了）
+         ↑                                        ↑
+    AI agent 调用                              fs 检测循环
+    有上下文                                  无上下文
+```
+
+- `auto-backup.js` 调用 snapshot 时只传 `{ trigger: 'auto', changedFileCount }`，没有 intent/agent/session
+- 只有 `snapshot_now` MCP 工具支持 intent 参数
+- 曾考虑"意图队列"（AI 写文件 → watcher 读文件关联），但存在 4 类并发竞态：
+
+| 竞态场景 | 描述 |
+|---------|------|
+| 多 Agent 竞争 | A 提交意图 → B 提交意图 → watcher 触发 → 绑谁的？ |
+| 意图-变更错位 | A 提交意图但未改文件 → B 改了另一个文件 → A 的意图被错绑到 B 的变更 |
+| 意图堆积 | 一个 cycle 内多个 agent 提交意图 → watcher 只产生一次 commit → 意图丢失或错配 |
+| 空意图残留 | Agent 提交意图后放弃 → 意图留在队列 → 被绑到下一次无关变更 |
+
+根本原因：**意图提交和文件变更是两个独立事件，跨进程 + 按时间绑定 = 无法原子化**。
+
+#### 方案：同进程 + 按文件路径绑定
+
+```
+┌─────────────── MCP Server 进程（V5） ──────────────────┐
+│                                                         │
+│  AI agent 调用              内存 activeEdits             │
+│  begin_edit({               Map<session, {              │
+│    intent,              →     intent, files[],          │
+│    files[],                   agent, timestamp,         │
+│    agent,                     ttl                       │
+│    session               }>                             │
+│  })                              ↓ 直接读取（同进程）    │
+│                                                         │
+│  Embedded Watcher 循环 ←─── 检测到 src/auth.ts 变更     │
+│  查 activeEdits:                                        │
+│    s1 声明了 [src/auth.ts] → 匹配 ✅                     │
+│    s2 声明了 [src/style.css] → 不匹配 ❌                 │
+│  → 创建 auto-backup commit 带 s1 的 intent              │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**核心优势**：
+- **同进程**：无 IPC、无文件 I/O、无并发竞争（Node.js 单线程 event loop）
+- **按文件路径绑定**：不同 Agent 改不同文件时各自匹配，无歧义
+- **TTL 自动过期**：空意图 5 分钟后自动清除，不会残留
+- **多 Agent 同文件**：标记为 `multi-agent overlap`，附上所有匹配意图（同时作为冲突检测信号）
+
+#### 并发场景处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| A 改 `auth.ts`，B 改 `style.css` | 各自匹配各自的 `begin_edit` scope，零歧义 |
+| A、B 都声明要改 `auth.ts` | `begin_edit` 时即检测到重叠，返回 advisory warning；auto-backup 附上两个 intent |
+| A 声明了意图但没改文件 | TTL 到期自动清除；`end_edit` 可提前关闭 |
+| 文件变更但没有任何 `begin_edit` | 降级为普通 auto-backup（和 V4 行为一致，无退化） |
+| AI 直接调 `snapshot_now(intent=...)` | 和现在一模一样，完全兼容 |
+
+#### 实现分期
+
+```
+Phase 1 (V5.0):
+  ├── always_watch: true → MCP server 内嵌 watcher 循环
+  ├── 新增 begin_edit / end_edit MCP 工具
+  ├── 内存 Map<session, EditScope> 管理活跃编辑意图
+  └── watcher 变更检测时查 Map，按文件路径匹配 intent → 写入 commit trailer
+
+Phase 2 (V5.x):
+  ├── begin_edit → 产生 intent_registered 事件（写入审计存储）
+  ├── 文件变更 → 产生 edit_applied 事件（关联 intent + before_ref）
+  ├── end_edit → 产生 intent_released 事件
+  └── 完整审计链闭环，支持 restore_from_event
+```
+
+#### 与"意图队列"方案的本质区别
+
+| | 意图队列（已否决） | embedded watcher + begin_edit |
+|---|---|---|
+| 通信方式 | 文件 I/O（跨进程） | 内存 Map（同进程） |
+| 绑定维度 | 时间顺序（先进先出） | 文件路径（精确匹配） |
+| 并发安全 | 4 类竞态条件 | 无竞态（单进程 event loop） |
+| 空意图处理 | 残留在文件中 | TTL 自动过期 + `end_edit` 显式关闭 |
+| 多 Agent 消歧 | 无法消歧 | 文件路径级消歧 + 冲突检测信号 |
+
 ### V5 主线 A：并发编辑安全（预防层）
 
 ```
@@ -650,6 +807,10 @@ V5 的关键不是"多打一行日志"，而是建立完整证据链：
 
 ### V5 完成标志（Definition of Done）
 
+- `always_watch: true` 配置生效后，MCP server 启动自动内嵌 watcher 循环，用户无需额外命令
+- `begin_edit` / `end_edit` MCP 工具可用，AI 能声明编辑意图和目标文件
+- embedded watcher 的自动备份能通过文件路径匹配关联 `begin_edit` 中的 intent/agent/session
+- 无 `begin_edit` 时自动备份行为与 V4 一致（无退化）
 - AI 能在高风险写入前注册意图并创建 `pre-edit` 快照
 - 用户能查询最近一次 AI 编辑的完整上下文
 - 给定 `event_id` 能找到对应快照并执行恢复

package/SKILL.md

@@ -571,9 +571,10 @@ Skip the block for unrelated turns.
 
 ## Hard Rules (Non-Negotiable)
 
-1. **MUST snapshot before high-risk ops** — git commit or shadow copy. No exceptions unless user explicitly declines.
+1. **MUST snapshot before ANY file write or delete** — call `snapshot_now` (with `intent`) before creating, editing, or deleting files. This is NOT optional and NOT just for "high-risk" operations. Every write is potentially destructive. No exceptions unless user explicitly says "不用备份" / "skip backup". If the MCP response includes `_warning` about the watcher being stopped, tell the user immediately.
 2. **MUST Read before Write** — never overwrite a file the agent hasn't read in the current turn.
 3. **MUST preserve current version before restore** — every restore operation must first snapshot the current state (§5a Step 4). Skip ONLY when: (a) user explicitly opts out, (b) current state is identical to target, or (c) no changes exist. If preservation fails, abort restore by default.
+3a. **MUST check watcher status** — if any MCP tool returns `_warning` about the watcher not running, immediately warn the user: "自动备份守护进程未运行，当前处于无保护状态。建议先启动 watcher 或在每次修改前手动调用 snapshot_now。" Do NOT silently continue editing files without protection.
 4. **Do not** treat Timeline/Checkpoints as the only or primary recovery path.
 5. **Do not** recommend Checkpoints as long-term or sole backup.
 6. **No automatic push** to remotes; local commits only unless user requests push.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "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

@@ -40,6 +40,12 @@ const I18N = {
     'alert.title':      'Alerts',
     'alert.none':       'No active alerts',
     'alert.active':     'Active Alert',
+    'alert.triggered':  'Triggered',
+    'alert.expires':    'Expires in',
+    'alert.detail':     '{count} files in {window}s (threshold: {threshold})',
+    'alert.expired':    'Expired',
+    'alert.history':    'Recent Alert History',
+    'alert.noHistory':  'No alert history',
 
     'backups.gitCommits':       'Git Commits',
     'backups.shadowSnapshots':  'Shadow Snapshots',
@@ -95,6 +101,7 @@ const I18N = {
     'trigger.manual':       'Manual (agent)',
     'trigger.pre-restore':  'Pre-Restore',
     'backups.col.summary':  'Changes',
+    'backups.search':       'Search files…',
     'summary.modified':     'Modified',
     'summary.added':        'Added',
     'summary.deleted':      'Deleted',
@@ -103,6 +110,13 @@ const I18N = {
     'drawer.field.intent':  'Intent',
     'drawer.field.agent':   'Agent',
     'drawer.field.session': 'Session',
+    'drawer.field.from':    'From (current)',
+    'drawer.field.restoreTo':'Restore to',
+    'drawer.field.restoreFile':'Restored file',
+    'drawer.restoreCmd':    'Copy Restore Command',
+    'drawer.restoreCmdFile':'Copy File Restore Command',
+
+    'watcher.lastScan':    'Last scan',
 
     'error.fetchFailed':    'Failed to fetch data',
     'error.sectionFailed':  'This section failed to load',
@@ -176,6 +190,8 @@ const I18N = {
     'detail.disk_critical':             '{gb} GB free — critically low',
     'detail.disk_free':                 '{gb} GB free',
     'detail.disk_unknown':              'could not determine free space',
+    'detail.lock_running':              'watcher running (pid={pid}, since {since})',
+    'detail.lock_stale':                'stale lock file (pid={pid} is dead) — safe to delete or run doctor_fix',
     'detail.lock_exists':               'lock file exists — another instance may be running. {info}',
     'detail.lock_none':                 'no lock file (no running instance)',
     'detail.node_ok':                   '{v}',
@@ -221,6 +237,12 @@ const I18N = {
     'alert.title':      '告警',
     'alert.none':       '无活跃告警',
     'alert.active':     '活跃告警',
+    'alert.triggered':  '触发时间',
+    'alert.expires':    '剩余有效',
+    'alert.detail':     '{count} 个文件在 {window} 秒内变更（阈值：{threshold}）',
+    'alert.expired':    '已过期',
+    'alert.history':    '近期告警历史',
+    'alert.noHistory':  '暂无告警记录',
 
     'backups.gitCommits':       'Git 提交数',
     'backups.shadowSnapshots':  '影子快照',
@@ -276,6 +298,7 @@ const I18N = {
     'trigger.manual':       '手动（Agent）',
     'trigger.pre-restore':  '恢复前快照',
     'backups.col.summary':  '变更',
+    'backups.search':       '搜索文件…',
     'summary.modified':     '修改',
     'summary.added':        '新增',
     'summary.deleted':      '删除',
@@ -284,6 +307,13 @@ const I18N = {
     'drawer.field.intent':  '操作意图',
     'drawer.field.agent':   'AI 模型',
     'drawer.field.session': '会话 ID',
+    'drawer.field.from':    '恢复前版本',
+    'drawer.field.restoreTo':'恢复目标',
+    'drawer.field.restoreFile':'恢复文件',
+    'drawer.restoreCmd':    '复制恢复命令',
+    'drawer.restoreCmdFile':'复制文件恢复命令',
+
+    'watcher.lastScan':    '最后扫描',
 
     'error.fetchFailed':    '数据拉取失败',
     'error.sectionFailed':  '此区块加载失败',
@@ -357,6 +387,8 @@ const I18N = {
     'detail.disk_critical':             '{gb} GB 可用——严重不足',
     'detail.disk_free':                 '{gb} GB 可用',
     'detail.disk_unknown':              '无法检测可用空间',
+    'detail.lock_running':              '守护进程运行中（pid={pid}，启动于 {since}）',
+    'detail.lock_stale':                '残留锁文件（pid={pid} 已终止）——可安全删除或运行 doctor_fix',
     'detail.lock_exists':               '锁文件存在——可能有其他实例正在运行。{info}',
     'detail.lock_none':                 '无锁文件（无运行中的实例）',
     'detail.node_ok':                   '{v}',
@@ -379,10 +411,12 @@ const state = {
   pageData: null,
   filteredBackups: [],
   backupFilter: 'all',
+  fileSearch: '',
   refreshTimer: null,
   tickTimer: null,
   lastRefreshAt: null,
   drawerOpen: null,
+  alertHistory: [],
 };
 
 const REFRESH_MS = 15000;
@@ -498,6 +532,8 @@ const DETAIL_PATTERNS = [
   { re: /^(.+?) GB free — critically low$/,                            key: 'detail.disk_critical', extract: ['gb'] },
   { re: /^could not determine free space$/,                            key: 'detail.disk_unknown' },
   { re: /^(.+?) GB free$/,                                             key: 'detail.disk_free', extract: ['gb'] },
+  { re: /^watcher running \(pid=(\d+), since (.+)\)$/,                  key: 'detail.lock_running', extract: ['pid', 'since'] },
+  { re: /^stale lock file \(pid=(\d+) is dead\)/,                      key: 'detail.lock_stale', extract: ['pid'] },
   { re: /^lock file exists — another instance may be running\. ?(.*)$/,key: 'detail.lock_exists', extract: ['info'] },
   { re: /^no lock file/,                                               key: 'detail.lock_none' },
   { re: /^(v\d+\.\d+\.\d+\S*) — recommended >=18$/,                   key: 'detail.node_old', extract: ['v'] },
@@ -775,6 +811,7 @@ function renderWatcherCard(watcher) {
   let st = 'stopped';
   if (watcher?.running) st = 'running';
   else if (watcher?.stale) st = 'stale';
+  const lastScan = state.lastRefreshAt ? relativeTime(new Date(state.lastRefreshAt).toISOString()) : null;
   el.innerHTML = `
     <div class="card-label">${t('watcher.title')}</div>
     <div class="card-status">
@@ -783,23 +820,55 @@ function renderWatcherCard(watcher) {
     </div>
     ${watcher?.pid ? `<div class="card-detail text-muted text-sm">${t('watcher.pid')}: ${watcher.pid}</div>` : ''}
     ${watcher?.startedAt ? `<div class="card-detail text-muted text-sm">${t('watcher.since')}: ${esc(formatTime(watcher.startedAt))}</div>` : ''}
+    ${watcher?.running && lastScan ? `<div class="card-detail text-muted text-sm">${t('watcher.lastScan')}: ${esc(lastScan)}</div>` : ''}
   `;
 }
 
 function renderAlertCard(alerts) {
   const el = $('#card-alert');
   if (!alerts?.active) {
+    let historyHtml = '';
+    if (state.alertHistory.length > 0) {
+      const rows = state.alertHistory.slice(-5).reverse().map(h =>
+        `<div class="alert-history-row text-sm text-muted">
+          <span>${esc(formatTime(h.timestamp))}</span>
+          <span>${t('alert.detail', { count: h.fileCount, window: h.windowSeconds, threshold: h.threshold })}</span>
+          <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>`;
+    }
     el.innerHTML = `
       <div class="card-label">${t('alert.title')}</div>
       <div class="card-status"><span class="status-dot status-healthy"></span><span>${t('alert.none')}</span></div>
+      ${historyHtml}
     `;
     return;
   }
   const a = alerts.latest || {};
+
+  // 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 });
+    if (state.alertHistory.length > 20) state.alertHistory = state.alertHistory.slice(-20);
+  }
+
+  const triggeredAt = a.timestamp ? formatTime(a.timestamp) : '-';
+  const expiresAt = a.expiresAt ? new Date(a.expiresAt) : null;
+  const remainMs = expiresAt ? expiresAt.getTime() - Date.now() : 0;
+  const remainSec = Math.max(0, Math.ceil(remainMs / 1000));
+  const remainMin = Math.floor(remainSec / 60);
+  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 || '?' });
+
   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>
-    <div class="card-detail text-muted text-sm">${esc(translateIssue(a.recommendation || a.message || ''))}</div>
+    <div class="alert-details">
+      <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>
+    </div>
   `;
 }
 
@@ -807,10 +876,17 @@ function renderAlertCard(alerts) {
 
 function renderBackupsSection(dashboard, backups) {
   renderBackupStats(dashboard, backups);
-  renderFilterBar();
+  renderFilterBar(backups);
+  renderFileSearch();
   renderBackupTable(backups);
 }
 
+function renderFileSearch() {
+  const el = $('#file-search-wrap');
+  if (!el) return;
+  el.innerHTML = `<input id="file-search" type="text" class="file-search-input" placeholder="${t('backups.search')}" value="${esc(state.fileSearch)}" />`;
+}
+
 function renderBackupStats(d, backups) {
   const gitCount = d.counts?.git?.commits || 0;
   const shadowCount = d.counts?.shadow?.snapshots || 0;
@@ -829,7 +905,11 @@ function renderBackupStats(d, backups) {
   `;
 }
 
-function renderFilterBar() {
+function renderFilterBar(backups) {
+  const allBackups = Array.isArray(backups) ? backups : (Array.isArray(state.pageData?.backups) ? state.pageData.backups : []);
+  const typeCounts = {};
+  for (const b of allBackups) { typeCounts[b.type] = (typeCounts[b.type] || 0) + 1; }
+
   const types = [
     { key: 'all',                label: 'backups.filterAll' },
     { key: 'git-auto-backup',   label: 'type.git-auto-backup' },
@@ -838,9 +918,12 @@ function renderFilterBar() {
     { key: 'shadow',            label: 'type.shadow' },
     { key: 'shadow-pre-restore',label: 'type.shadow-pre-restore' },
   ];
-  $('#backup-filters').innerHTML = types.map(t2 =>
-    `<button class="filter-btn ${state.backupFilter === t2.key ? 'active' : ''}" data-filter="${t2.key}">${t(t2.label)}</button>`
-  ).join('');
+  const total = allBackups.length;
+  $('#backup-filters').innerHTML = types.map(t2 => {
+    const count = t2.key === 'all' ? total : (typeCounts[t2.key] || 0);
+    if (t2.key !== 'all' && count === 0) return '';
+    return `<button class="filter-btn ${state.backupFilter === t2.key ? 'active' : ''}" data-filter="${t2.key}">${t(t2.label)} <span class="filter-count">(${count})</span></button>`;
+  }).join('');
 }
 
 function translateSummary(raw) {
@@ -859,7 +942,10 @@ function formatSummaryCell(b) {
   }
 
   let line2 = '';
-  if (b.intent) {
+  if (b.from && b.restoreTo) {
+    const label = b.restoreFile ? `${esc(b.restoreFile)}: ` : '';
+    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>`;
   } else if (b.message && !b.message.startsWith('guard:')) {
@@ -870,7 +956,15 @@ function formatSummaryCell(b) {
   let line3 = '';
   if (b.summary) {
     const categories = b.summary.split('; ').map(s => translateSummary(s));
-    line3 = categories.map(c => `<div class="summary-detail-line">${esc(c)}</div>`).join('');
+    const MAX_VISIBLE = 2;
+    if (categories.length <= MAX_VISIBLE) {
+      line3 = categories.map(c => `<div class="summary-detail-line">${esc(c)}</div>`).join('');
+    } 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>`;
+    }
   }
 
   if (!line1 && !line2 && !line3) return '<span class="text-muted text-sm">-</span>';
@@ -882,10 +976,21 @@ function renderBackupTable(backups) {
     $('#backup-table-wrap').innerHTML = `<div class="error-panel">${t('error.sectionFailed')}</div>`;
     return;
   }
-  state.filteredBackups = state.backupFilter === 'all'
+  let filtered = state.backupFilter === 'all'
     ? backups
     : backups.filter(b => b.type === state.backupFilter);
 
+  if (state.fileSearch) {
+    const q = state.fileSearch.toLowerCase();
+    filtered = filtered.filter(b =>
+      (b.summary && b.summary.toLowerCase().includes(q)) ||
+      (b.message && b.message.toLowerCase().includes(q)) ||
+      (b.intent && b.intent.toLowerCase().includes(q)) ||
+      (b.restoreFile && b.restoreFile.toLowerCase().includes(q))
+    );
+  }
+  state.filteredBackups = filtered;
+
   if (state.filteredBackups.length === 0) {
     $('#backup-table-wrap').innerHTML = `<div class="empty-state">${t('backups.noBackups')}</div>`;
     return;
@@ -1004,6 +1109,9 @@ function openRestoreDrawer(backup) {
   if (backup.intent) fields.push({ key: 'drawer.field.intent', val: backup.intent });
   if (backup.agent) fields.push({ key: 'drawer.field.agent', val: backup.agent });
   if (backup.session) fields.push({ key: 'drawer.field.session', val: backup.session });
+  if (backup.from) fields.push({ key: 'drawer.field.from', val: backup.from });
+  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');
@@ -1013,6 +1121,11 @@ function openRestoreDrawer(backup) {
   const refText = backup.ref || backup.shortHash || backup.timestamp || '';
   const jsonText = JSON.stringify(backup, null, 2);
 
+  const isGit = backup.type?.startsWith('git');
+  const hash = backup.commitHash || backup.shortHash || '';
+  const restoreProjectCmd = isGit && hash ? `restore_project({ version: "${hash}", mode: "execute" })` : '';
+  const restoreFileCmd = isGit && hash ? `restore_file({ file: "<filename>", version: "${hash}" })` : '';
+
   body.innerHTML = `
     ${fields.map(f => `
       <div class="restore-field">
@@ -1028,12 +1141,29 @@ function openRestoreDrawer(backup) {
       <button class="btn btn-sm" data-copy-json>${t('drawer.copyJson')}</button>
       <button class="btn btn-sm" id="preview-toggle">${t('drawer.preview')}</button>
     </div>
+    ${restoreProjectCmd ? `
+    <div class="restore-cmd-section">
+      <div class="restore-cmd-label text-sm text-muted">MCP Restore Commands</div>
+      <div class="restore-cmd-row">
+        <code class="restore-cmd-code">${esc(restoreProjectCmd)}</code>
+        <button class="btn btn-sm btn-restore-cmd" data-copy-restore-project>${t('drawer.restoreCmd')}</button>
+      </div>
+      <div class="restore-cmd-row">
+        <code class="restore-cmd-code">${esc(restoreFileCmd)}</code>
+        <button class="btn btn-sm btn-restore-cmd" data-copy-restore-file>${t('drawer.restoreCmdFile')}</button>
+      </div>
+    </div>
+    ` : ''}
     <div id="json-preview-wrap" class="hidden">
       <pre class="json-preview">${esc(jsonText)}</pre>
     </div>
   `;
 
   body.querySelector('[data-copy-json]')?.addEventListener('click', () => copyText(jsonText));
+  if (restoreProjectCmd) {
+    body.querySelector('[data-copy-restore-project]')?.addEventListener('click', () => copyText(restoreProjectCmd));
+    body.querySelector('[data-copy-restore-file]')?.addEventListener('click', () => copyText(restoreFileCmd));
+  }
   body.querySelector('#preview-toggle')?.addEventListener('click', () => {
     const wrap = body.querySelector('#json-preview-wrap');
     wrap.classList.toggle('hidden');
@@ -1101,7 +1231,7 @@ function setupEvents() {
     state.currentProjectId = e.target.value;
     state.backupFilter = 'all';
     stopRefresh();
-    showLoading();
+    showSkeleton();
     try { await loadPageData(); renderAll(); }
     catch (err) { showGlobalError(err.message); }
     startRefresh();
@@ -1121,13 +1251,29 @@ function setupEvents() {
     state.backupFilter = btn.dataset.filter;
     const backups = state.pageData?.backups;
     if (Array.isArray(backups)) {
-      renderFilterBar();
+      renderFilterBar(backups);
       renderBackupTable(backups);
     }
   });
 
-  // Backup table row click (event delegation)
+  // File search (event delegation on parent)
+  document.addEventListener('input', (e) => {
+    if (e.target.id === 'file-search') {
+      state.fileSearch = e.target.value;
+      const backups = state.pageData?.backups;
+      if (Array.isArray(backups)) renderBackupTable(backups);
+    }
+  });
+
+  // Summary expand toggle (must come before row click to prevent drawer open)
   $('#backup-table-wrap').addEventListener('click', (e) => {
+    const toggleBtn = e.target.closest('[data-summary-toggle]');
+    if (toggleBtn) {
+      e.stopPropagation();
+      const cell = toggleBtn.closest('.summary-stack');
+      if (cell) cell.classList.toggle('summary-expanded');
+      return;
+    }
     const row = e.target.closest('tr[data-bi]');
     if (!row) return;
     const idx = parseInt(row.dataset.bi, 10);

package/references/dashboard/public/index.html

@@ -57,6 +57,7 @@
       <h2 class="section-title" data-i18n="backups.title">Backups &amp; Recovery</h2>
       <div id="backup-stats" class="stats-row"><div class="skeleton-row"></div></div>
       <div id="backup-filters" class="filter-bar"></div>
+      <div id="file-search-wrap" class="file-search-wrap"></div>
       <div id="backup-table-wrap" class="table-wrap"><div class="skeleton-table"></div></div>
     </section>
 

package/references/dashboard/public/style.css

@@ -349,6 +349,19 @@ main {
   max-width: 400px;
   line-height: 1.4;
 }
+.summary-restore-ctx {
+  font-size: 12px;
+  color: var(--amber);
+  background: var(--amber-bg);
+  padding: 4px 10px;
+  border-radius: 4px;
+  border-left: 3px solid var(--amber);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 400px;
+  line-height: 1.4;
+}
 .summary-message {
   font-size: 12px;
   color: var(--text-primary);
@@ -375,6 +388,25 @@ main {
 }
 .summary-detail-line:first-child { padding-top: 2px; }
 
+.summary-collapsed {
+  display: none;
+}
+.summary-expanded .summary-collapsed {
+  display: block;
+}
+.summary-toggle-btn {
+  background: none;
+  border: none;
+  color: var(--blue);
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 2px 0;
+  transition: color var(--transition);
+}
+.summary-toggle-btn:hover { color: var(--text-heading); }
+.summary-expanded .summary-toggle-btn { display: none; }
+
 .summary-pre {
   font-size: 12px;
   line-height: 1.6;
@@ -850,6 +882,143 @@ main {
 }
 .skeleton-table::after { width: 75%; opacity: .6; }
 
+/* ── Alert Card Details ───────────────────────────────────── */
+
+.alert-details {
+  margin-top: 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.alert-detail-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  color: var(--text-secondary);
+}
+.alert-detail-label {
+  font-weight: 600;
+  color: var(--text-tertiary);
+  min-width: 72px;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+}
+.alert-countdown {
+  color: var(--yellow);
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+}
+.alert-numbers {
+  margin-top: 4px;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--yellow);
+  background: var(--yellow-bg);
+  padding: 6px 12px;
+  border-radius: var(--radius-sm);
+  border-left: 3px solid var(--yellow);
+}
+
+.alert-history {
+  margin-top: 12px;
+  border-top: 1px solid var(--border-subtle);
+  padding-top: 8px;
+}
+.alert-history-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+  color: var(--text-tertiary);
+  margin-bottom: 6px;
+}
+.alert-history-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 3px 0;
+  font-size: 11px;
+}
+.badge-expired {
+  background: var(--gray-bg);
+  color: var(--gray);
+  border-color: rgba(100,116,139,.18);
+  font-size: 9px;
+  padding: 1px 6px;
+}
+
+/* ── File Search ─────────────────────────────────────────── */
+
+.file-search-wrap {
+  margin-bottom: 12px;
+}
+.file-search-input {
+  width: 100%;
+  max-width: 360px;
+  background: var(--bg-secondary);
+  color: var(--text-primary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 8px 14px;
+  font-size: 13px;
+  font-family: inherit;
+  transition: border-color var(--transition);
+}
+.file-search-input::placeholder { color: var(--text-tertiary); }
+.file-search-input:focus {
+  outline: none;
+  border-color: var(--blue);
+  box-shadow: 0 0 0 3px var(--blue-bg);
+}
+
+/* ── Filter Count ────────────────────────────────────────── */
+
+.filter-count {
+  font-size: 10px;
+  opacity: .65;
+  font-weight: 400;
+}
+
+/* ── Restore Command Section ─────────────────────────────── */
+
+.restore-cmd-section {
+  margin-top: 18px;
+  padding-top: 16px;
+  border-top: 1px solid var(--border);
+}
+.restore-cmd-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  color: var(--text-tertiary);
+  margin-bottom: 10px;
+}
+.restore-cmd-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+.restore-cmd-code {
+  flex: 1;
+  font-family: 'JetBrains Mono', 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+  font-size: 11px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  padding: 8px 12px;
+  color: var(--green);
+  word-break: break-all;
+  line-height: 1.5;
+}
+.btn-restore-cmd {
+  flex-shrink: 0;
+  white-space: nowrap;
+}
+
 /* ── Utility ──────────────────────────────────────────────── */
 
 .hidden { display: none !important; }

package/references/lib/auto-backup.js

@@ -2,11 +2,10 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execFileSync } = require('child_process');
 const {
   color, loadConfig, gitAvailable, git, isGitRepo, gitDir: getGitDir,
   walkDir, filterFiles, buildManifest, loadManifest, saveManifest,
-  manifestChanged, createLogger, unquoteGitPath,
+  manifestChanged, createLogger,
 } = require('./utils');
 const { createGitSnapshot, createShadowCopy } = require('./core/snapshot');
 const { cleanShadowRetention, cleanGitRetention } = require('./core/backups');
@@ -235,33 +234,9 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
     }
     if (!hasChanges) continue;
 
-    // V4: Record change event and check for anomalies
+    // Shadow: pre-compute changed file count from manifest diff (already accurate)
     let changedFileCount = 0;
-    let porcelain = '';
-    if (repo) {
-      // Use execFileSync directly — git() helper's trim() strips leading spaces
-      // from porcelain output, corrupting the first line when it starts with ' '.
-      try {
-        porcelain = execFileSync('git', ['status', '--porcelain'], {
-          cwd: projectDir, stdio: 'pipe', encoding: 'utf-8',
-        });
-      } catch { /* ignore */ }
-      if (porcelain) {
-        const lines = porcelain.split('\n').filter(Boolean);
-        if (cfg.protect.length === 0 && cfg.ignore.length === 0) {
-          changedFileCount = lines.length;
-        } else {
-          const changedPaths = lines.map(line => {
-            const filePart = line.substring(3);
-            const arrowIdx = filePart.indexOf(' -> ');
-            const raw = arrowIdx >= 0 ? filePart.substring(arrowIdx + 4) : filePart;
-            return unquoteGitPath(raw);
-          });
-          const fakeFiles = changedPaths.map(rel => ({ rel, full: path.join(projectDir, rel) }));
-          changedFileCount = filterFiles(fakeFiles, cfg).length;
-        }
-      }
-    } else if (pendingManifest) {
+    if (!repo && pendingManifest) {
       if (!lastManifest) {
         changedFileCount = Object.keys(pendingManifest).length;
       } else {
@@ -278,18 +253,12 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     }
 
-    recordChange(tracker, changedFileCount);
-    const anomalyResult = checkAnomaly(tracker);
-    if (anomalyResult.anomaly && anomalyResult.alert && !anomalyResult.suppressed) {
-      saveAlert(projectDir, anomalyResult.alert);
-      logger.warn(`ALERT: ${anomalyResult.alert.fileCount} files changed in ${anomalyResult.alert.windowSeconds}s (threshold: ${anomalyResult.alert.threshold})`);
-    }
-
-    // Git snapshot via Core
+    // Git snapshot via Core — changedFileCount comes from diff-tree (accurate incremental)
     if ((cfg.backup_strategy === 'git' || cfg.backup_strategy === 'both') && repo) {
-      const context = { trigger: 'auto', changedFileCount };
+      const context = { trigger: 'auto' };
       const snapResult = createGitSnapshot(projectDir, cfg, { branchRef, context });
       if (snapResult.status === 'created') {
+        changedFileCount = snapResult.changedCount != null ? snapResult.changedCount : 0;
         let msg = `Git snapshot ${snapResult.shortHash} (${snapResult.fileCount} files)`;
         if (snapResult.secretsExcluded) {
           msg += ` [secrets excluded: ${snapResult.secretsExcluded.join(', ')}]`;
@@ -302,6 +271,14 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
       }
     }
 
+    // V4: Record change event and check for anomalies (after snapshot, using accurate count)
+    recordChange(tracker, changedFileCount);
+    const anomalyResult = checkAnomaly(tracker);
+    if (anomalyResult.anomaly && anomalyResult.alert && !anomalyResult.suppressed) {
+      saveAlert(projectDir, anomalyResult.alert);
+      logger.warn(`ALERT: ${anomalyResult.alert.fileCount} files changed in ${anomalyResult.alert.windowSeconds}s (threshold: ${anomalyResult.alert.threshold})`);
+    }
+
     // Shadow copy via Core
     if (cfg.backup_strategy === 'shadow' || cfg.backup_strategy === 'both') {
       const shadowResult = createShadowCopy(projectDir, cfg, { backupDir });

package/references/lib/core/backups.js

@@ -48,6 +48,9 @@ const TRAILER_MAP = {
   'Intent':        { key: 'intent' },
   'Agent':         { key: 'agent' },
   'Session':       { key: 'session' },
+  'From':          { key: 'from' },
+  'Restore-To':   { key: 'restoreTo' },
+  'File':          { key: 'restoreFile' },
 };
 
 function parseCommitTrailers(body) {

package/references/lib/core/core.test.js

@@ -621,6 +621,46 @@ test('restoreFile respects pre_restore_backup=never from config', () => {
   }
 });
 
+test('restoreFile rejects directory pathspec (git tree)', () => {
+  const tmpDir = createTempGitRepo();
+  try {
+    const headHash = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: tmpDir, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    const result = restoreFile(tmpDir, 'src', headHash, { preserveCurrent: false });
+    assert.strictEqual(result.status, 'error');
+    assert.ok(result.error.includes('tree') || result.error.includes('directory'), `expected tree/directory error, got: ${result.error}`);
+  } finally {
+    cleanupDir(tmpDir);
+  }
+});
+
+test('restoreFile rejects protected .cursor directory', () => {
+  const tmpDir = createTempGitRepo();
+  try {
+    fs.mkdirSync(path.join(tmpDir, '.cursor'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, '.cursor', 'mcp.json'), '{}');
+    execFileSync('git', ['add', '-A'], { cwd: tmpDir, stdio: 'pipe' });
+    execFileSync('git', ['commit', '-m', 'add .cursor'], { cwd: tmpDir, stdio: 'pipe' });
+    const headHash = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: tmpDir, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    const result = restoreFile(tmpDir, '.cursor', headHash, { preserveCurrent: false });
+    assert.strictEqual(result.status, 'error');
+    assert.ok(result.error.includes('protected'), `expected protected path error, got: ${result.error}`);
+  } finally {
+    cleanupDir(tmpDir);
+  }
+});
+
+test('restoreFile rejects project root "."', () => {
+  const tmpDir = createTempGitRepo();
+  try {
+    const headHash = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: tmpDir, stdio: 'pipe', encoding: 'utf-8' }).trim();
+    const result = restoreFile(tmpDir, '.', headHash, { preserveCurrent: false });
+    assert.strictEqual(result.status, 'error');
+    assert.ok(result.error.includes('project root') || result.error.includes('specific file'), `expected root rejection, got: ${result.error}`);
+  } finally {
+    cleanupDir(tmpDir);
+  }
+});
+
 test('createPreRestoreSnapshot creates ref under refs/guard/pre-restore/', () => {
   const tmpDir = createTempGitRepo();
   try {

package/references/lib/core/doctor.js

@@ -217,14 +217,28 @@ function runDiagnostics(projectDir) {
     check('Disk space', 'WARN', 'could not determine free space');
   }
 
-  // 12. Lock file
+  // 12. Lock file — distinguish running watcher from stale lock
   const lockFile = gDir
     ? path.join(gDir, 'cursor-guard.lock')
     : path.join(backupDir, 'cursor-guard.lock');
   if (fs.existsSync(lockFile)) {
     let content = '';
     try { content = fs.readFileSync(lockFile, 'utf-8').trim(); } catch { /* ignore */ }
-    check('Lock file', 'WARN', `lock file exists — another instance may be running. ${content}`);
+    const pidMatch = content.match(/pid=(\d+)/);
+    const startedMatch = content.match(/started=(.+)/);
+    const lockPid = pidMatch ? parseInt(pidMatch[1], 10) : null;
+    let pidAlive = false;
+    if (lockPid) {
+      try { process.kill(lockPid, 0); pidAlive = true; } catch { /* not running */ }
+    }
+    if (lockPid && pidAlive) {
+      const since = startedMatch ? startedMatch[1] : 'unknown';
+      check('Lock file', 'PASS', `watcher running (pid=${lockPid}, since ${since})`);
+    } else if (lockPid && !pidAlive) {
+      check('Lock file', 'WARN', `stale lock file (pid=${lockPid} is dead) — safe to delete or run doctor_fix`);
+    } else {
+      check('Lock file', 'WARN', `lock file exists — another instance may be running. ${content}`);
+    }
   } else {
     check('Lock file', 'PASS', 'no lock file (no running instance)');
   }

package/references/lib/core/restore.js

@@ -31,7 +31,7 @@ const GUARD_CONFIGS = ['.cursor-guard.json', '.gitignore'];
 
 function isToolPath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
-  if (TOOL_DIRS.some(d => normalized.startsWith(d))) return true;
+  if (TOOL_DIRS.some(d => normalized.startsWith(d) || normalized === d.replace(/\/$/, ''))) return true;
   if (GUARD_CONFIGS.includes(normalized)) return true;
   return false;
 }
@@ -93,7 +93,7 @@ function restoreFile(projectDir, file, source, opts = {}) {
 
   // Pre-restore snapshot (git path)
   if (preserveCurrent && repo) {
-    const preRestoreResult = createPreRestoreSnapshot(projectDir, file);
+    const preRestoreResult = createPreRestoreSnapshot(projectDir, file, { source, file: pathCheck.normalized });
     if (preRestoreResult.status === 'created') {
       result.preRestoreRef = preRestoreResult.ref;
       result.preRestoreShortHash = preRestoreResult.shortHash;
@@ -131,6 +131,10 @@ function restoreFile(projectDir, file, source, opts = {}) {
   // Restore from shadow copy
   if (isShadowSource) {
     try {
+      const stat = fs.statSync(shadowDir);
+      if (stat.isDirectory()) {
+        return { status: 'error', restoredFrom: source, error: `'${file}' is a directory, not a file — use restore_project for directory-level restores` };
+      }
       const dest = path.join(projectDir, file);
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       fs.copyFileSync(shadowDir, dest);
@@ -144,24 +148,21 @@ function restoreFile(projectDir, file, source, opts = {}) {
 
   // Restore from git
   try {
-    // Verify the source ref/hash is valid
     const resolved = git(['rev-parse', '--verify', source], { cwd: projectDir, allowFail: true });
     if (!resolved) {
       return { status: 'error', restoredFrom: source, error: `cannot resolve git source: ${source}` };
     }
 
-    // Check that the file exists in the source
-    const fileExists = git(['cat-file', '-e', `${resolved}:${file}`], { cwd: projectDir, allowFail: true });
-    if (fileExists === null) {
-      // cat-file -e returns empty on success with allowFail, null on error
-      // Try ls-tree instead
-      const lsOut = git(['ls-tree', resolved, '--', file], { cwd: projectDir, allowFail: true });
-      if (!lsOut) {
-        return { status: 'error', restoredFrom: source, error: `file '${file}' not found in source ${source}` };
-      }
+    // Verify the target is a blob (file), not a tree (directory)
+    const objType = git(['cat-file', '-t', `${resolved}:${pathCheck.normalized}`], { cwd: projectDir, allowFail: true });
+    if (!objType) {
+      return { status: 'error', restoredFrom: source, error: `'${file}' not found in source ${source}` };
+    }
+    if (objType !== 'blob') {
+      return { status: 'error', restoredFrom: source, error: `'${file}' is a ${objType} (directory), not a file — use restore_project for directory-level restores` };
     }
 
-    execFileSync('git', ['restore', `--source=${resolved}`, '--', file], {
+    execFileSync('git', ['restore', `--source=${resolved}`, '--', pathCheck.normalized], {
       cwd: projectDir, stdio: 'pipe',
     });
 
@@ -295,7 +296,7 @@ function executeProjectRestore(projectDir, source, opts = {}) {
   const result = { filesRestored: 0, files: effectiveFiles };
 
   if (preserveCurrent) {
-    const snap = createPreRestoreSnapshot(projectDir, null);
+    const snap = createPreRestoreSnapshot(projectDir, null, { source });
     if (snap.status === 'created') {
       result.preRestoreRef = snap.ref;
       result.preRestoreShortHash = snap.shortHash;
@@ -370,9 +371,12 @@ function executeProjectRestore(projectDir, source, opts = {}) {
  *
  * @param {string} projectDir
  * @param {string} [scope] - Specific file to check for changes, or null for all
+ * @param {object} [opts]
+ * @param {string} [opts.source] - Target restore source (commit hash or ref)
+ * @param {string} [opts.file] - File being restored (single-file restore only)
  * @returns {{ status: 'created'|'skipped'|'error', ref?: string, shortHash?: string, error?: string }}
  */
-function createPreRestoreSnapshot(projectDir, scope) {
+function createPreRestoreSnapshot(projectDir, scope, opts = {}) {
   const gDir = getGitDir(projectDir);
   if (!gDir) return { status: 'error', error: 'not a git repository' };
 
@@ -410,6 +414,12 @@ function createPreRestoreSnapshot(projectDir, scope) {
 
     let msg = `guard: pre-restore snapshot ${ts}`;
     msg += '\n\nTrigger: pre-restore';
+    msg += `\nFrom: ${head.substring(0, 7)}`;
+    if (opts.source) {
+      const targetShort = git(['rev-parse', '--short', opts.source], { cwd, allowFail: true }) || opts.source;
+      msg += `\nRestore-To: ${targetShort}`;
+    }
+    if (opts.file) msg += `\nFile: ${opts.file}`;
     const commitHash = execFileSync('git', [
       'commit-tree', tree, '-p', head, '-m', msg,
     ], { cwd, stdio: 'pipe', encoding: 'utf-8' }).trim();

package/references/mcp/server.js

@@ -15,6 +15,8 @@ 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 pkg = require('../../package.json');
 
 // ── Alert injection helper ──────────────────────────────────────
@@ -32,6 +34,33 @@ function injectAlert(projectPath, result) {
   return result;
 }
 
+// ── Watcher status check ────────────────────────────────────────
+
+function isWatcherRunning(projectDir) {
+  const fs = require('fs');
+  const gDir = getGitDir(projectDir);
+  const lockFile = gDir
+    ? path.join(gDir, 'cursor-guard.lock')
+    : path.join(projectDir, '.cursor-guard-backup', 'cursor-guard.lock');
+  if (!fs.existsSync(lockFile)) return false;
+  try {
+    const content = fs.readFileSync(lockFile, 'utf-8');
+    const pidMatch = content.match(/pid=(\d+)/);
+    if (pidMatch) {
+      process.kill(parseInt(pidMatch[1], 10), 0);
+      return true;
+    }
+  } catch { /* pid gone or lock unreadable */ }
+  return false;
+}
+
+function injectWatcherWarning(projectPath, result) {
+  if (!isWatcherRunning(projectPath)) {
+    result._warning = 'Watcher is NOT running — auto-backup protection is inactive. Any file changes made without a manual snapshot_now call will NOT be captured. Consider starting the watcher or calling snapshot_now before making changes.';
+  }
+  return result;
+}
+
 // ── Server ──────────────────────────────────────────────────────
 
 const server = new McpServer({
@@ -50,6 +79,7 @@ server.tool(
   async ({ path: projectPath }) => {
     const resolved = path.resolve(projectPath);
     const result = injectAlert(resolved, runDiagnostics(resolved));
+    injectWatcherWarning(resolved, result);
     return {
       content: [{
         type: 'text',
@@ -128,6 +158,7 @@ server.tool(
     }
 
     injectAlert(resolved, results);
+    injectWatcherWarning(resolved, results);
 
     return {
       content: [{
@@ -154,6 +185,7 @@ server.tool(
     const result = injectAlert(resolved, restoreFile(resolved, file, source, {
       preserveCurrent: preserve_current,
     }));
+    injectWatcherWarning(resolved, result);
     return {
       content: [{
         type: 'text',
@@ -187,6 +219,7 @@ server.tool(
       preserveCurrent: preserve_current,
       cleanUntracked: clean_untracked,
     }));
+    injectWatcherWarning(resolved, result);
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
   }
 );