cursor-guard 4.3.5 → 4.4.1

package/README.md

@@ -377,6 +377,15 @@ The skill activates on these signals:
 
 ## Changelog
 
+### v4.4.0 — V4 Final
+
+- **Fix**: First snapshot now generates "Added N: file1, file2, ..." summary instead of blank — previously the very first backup had no summary because there was no parent tree to diff against
+- **Feature**: `--dashboard` flag for watcher — `npx cursor-guard-backup --path <dir> --dashboard` starts the web dashboard alongside the watcher in a single process. Optional port: `--dashboard 4000`. Auto-increments if port is busy
+- **Feature**: Doctor check "Git retention" — warns when git backup commits exceed 500 and `git_retention.enabled` is `false`, guiding users to enable auto-pruning before refs grow unbounded
+- **Feature**: Doctor check "Backup integrity" — verifies that the latest auto-backup commit's tree object is reachable via `git cat-file -t`, catching silent corruption early
+- **Improve**: `cursor-guard-init` now detects existing `.cursor-guard.json` and displays an upgrade notice instead of silently overwriting
+- **Improve**: Dashboard server refactored to export `startDashboardServer()` for embedding into other processes
+
 ### v4.3.5
 
 - **Fix**: Backup summary now uses incremental `diff-tree` instead of `git status --porcelain` — previously summary always showed cumulative changes since HEAD, now correctly shows changes since the last auto-backup

package/README.zh-CN.md

@@ -377,6 +377,15 @@ node references\dashboard\server.js --path "D:\MyProject"
 
 ## 更新日志
 
+### v4.4.0 — V4 收官版
+
+- **修复**：首次快照现在会生成 "Added N: file1, file2, ..." 摘要，而不是空白——之前第一次备份因为没有 parent tree 对比所以 summary 始终为空
+- **功能**：Watcher `--dashboard` 参数——`npx cursor-guard-backup --path <dir> --dashboard` 启动时同时启动 Web 仪表盘，单进程完成监控+查看。可选端口：`--dashboard 4000`，端口被占自动递增
+- **功能**：Doctor 新增 "Git retention" 检查——当 Git 备份 commit 数超过 500 且 `git_retention.enabled` 为 `false` 时发出 WARN，引导用户开启自动清理防止 ref 无限增长
+- **功能**：Doctor 新增 "Backup integrity" 检查——通过 `git cat-file -t` 验证最近一次 auto-backup commit 的 tree 对象是否可达，尽早发现静默损坏
+- **改进**：`cursor-guard-init` 现在检测已有 `.cursor-guard.json`，显示升级提示而非静默覆盖
+- **改进**：Dashboard server 重构，导出 `startDashboardServer()` 供嵌入其他进程使用
+
 ### v4.3.5
 
 - **修复**：备份摘要（Summary）现使用增量 `diff-tree` 替代 `git status --porcelain`——之前 summary 始终显示自 HEAD 以来的累计差异，现在正确显示自上次 auto-backup 以来的增量变化

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.3.3`  
-> **文档状态**：`V2` ~ `V4.3` 已实施（含 V5 intent 基础），`V5` 主体规划中
+> **当前版本**：`V4.4.0`（V4 收官版）  
+> **文档状态**：`V2` ~ `V4.4.0` 已实施（含 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` | 可证明 | + 可验证信任 + 治理层 | "能证明安全流程被执行了" |
@@ -65,7 +65,7 @@ V2-V3 的目标是让用户"离不开"，V6-V7 的目标是让行业"绕不开"
 | `MCP Server` | `V3.1-V4.0` ✅ 已完成 | 9 个工具，Agent 标准调用入口，结构化 JSON 返回 | 否 |
 | `智能提醒 / 可观测` | `V4.0` ✅ 已完成 | 主动发现风险、汇总健康状态（anomaly + dashboard） | 否 |
 | `Web 仪表盘` | `V4.2` ✅ 已完成 | 本地只读 Web UI，备份/恢复点/诊断/保护范围，中英双语 | 否 |
-| `备份上下文 + Intent` | `V4.3` ✅ 已完成 | 结构化 commit trailer（Files-Changed/Summary/Trigger/Intent/Agent/Session），仪表盘可追溯 | 否 |
+| `备份上下文 + Intent` | `V4.3` ✅ 已完成 | 结构化 commit trailer（Files-Changed/Summary/Trigger/Intent/Agent/Session），增量 diff-tree 真实摘要，仪表盘可追溯 | 否 |
 | `变更控制层` | `V5` 规划（intent 基础已在 V4.3 落地） | 覆盖编辑意图、冲突告警、影响半径、审计事件、按事件恢复 | 否 |
 | `开放协议 / 团队工作流` | `V6` 规划 | 把变更控制能力提炼成跨工具协议、适配器和 CI 查询入口 | 否 |
 | `治理 / 可验证层` | `V7` 规划 | 让“是否走过安全流程”变成可以证明、可以审计、可以验证的事实 | 否 |
@@ -454,6 +454,9 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | V4.3.1 | `restore_project` 保护 `.gitignore`；`cursor-guard-index.lock` 清理；summary 按 protect/ignore 过滤 + 分类格式 | ✅ |
 | V4.3.2 | `cursor-guard-init` 自动添加根目录 `node_modules/` 到 `.gitignore`；doctor MCP 版本提示含重载快捷键 | ✅ |
 | V4.3.3 | **Intent 上下文**（V5 基础前置）：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，Git trailer 存储，仪表盘展示意图徽章和完整审计字段 | ✅ |
+| 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.2 的 Web 仪表盘最初在 V4.0 规划中标记为"不做"，但用户需求明确后实施。事实证明只读仪表盘投入产出比合理，且不违反安全原则。
 
@@ -511,7 +514,7 @@ V5 不是"三个方向选一个"，而是把下面这条链路做完整：
 
 | 模块 / 能力 | AI 要做什么 | 建议产物 | 完成标准 |
 |---|---|---|---|
-| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件。**基础版已在 V4.3.3 落地**：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，存储为 Git commit trailer，仪表盘可展示 |
+| `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 解析 |
@@ -952,8 +955,8 @@ V7.2  完整 attestation（安全操作证明链）
 
 | | V2 | V3 | V4 | V5 | V6 | V7 |
 |---|---|---|---|---|---|---|
-| **一句话** | 能恢复 | 更稳更省 | 主动提醒 + 可观测 + Intent | 变更闭环 | 跨工具标准 | 可证明 |
-| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 + Web 仪表盘 + Intent 基础 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
+| **一句话** | 能恢复 | 更稳更省 | 主动提醒 + 可观测 + 可追溯 | 变更闭环 | 跨工具标准 | 可证明 |
+| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 + Web 仪表盘 + Intent + 增量摘要 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
 | **Agent 调用** | 拼 shell | 优先 MCP | MCP + 主动建议 | MCP + 意图 / 审计 / 恢复 | 标准接口 + 适配器 | 标准接口 + 审计 |
 | **安装门槛** | 最低 | 不变 | 不变 | 略增 | 看具体实现 | 看具体实现 |
 | **适合谁** | 所有人 | 所有人 | 所有人 | 重度 AI 用户 + 团队试点 | 工具开发者 + 团队 | 企业 + 合规场景 |
@@ -975,10 +978,17 @@ V3.4  ──────  ✅ MCP 自检
                │  前提：MCP 调用成功率 > 95%，token 消耗可观测下降
                ▼
 V4.0  ──────  ✅ 智能恢复建议 + 备份健康看板 + 4 轮代码审查加固（138 测试）
-V4.1  ──────  ✅ 用户反馈修复
-V4.2  ──────  ✅ Web 仪表盘（只读、双语、多项目）+ 代码审查修复
-V4.3  ──────  ✅ 备份上下文元数据 + Intent 上下文 + restore 安全加固  ← 当前版本
-V4.x  ──────  候选支线（完整性校验 / 更丰富的审计查询）
+V4.1  ──────  ✅ 用户反馈修复（fileCount 精度、安装流程、PowerShell 兼容）
+V4.2.0 ─────  ✅ Web 仪表盘（只读、双语、多项目、聚合 API）
+V4.2.1 ─────  ✅ 代码审查修复（t() replaceAll、未用导入、过滤栏补全）
+V4.2.2 ─────  ✅ restore 保护 .cursor-guard.json + init 提示 git commit
+V4.3.0 ─────  ✅ 备份上下文元数据（Git trailer: Files-Changed / Summary / Trigger）
+V4.3.1 ─────  ✅ restore 保护 .gitignore + lock 清理 + summary 过滤/分类
+V4.3.2 ─────  ✅ init 自动添加 node_modules/ 到 .gitignore + doctor 重载提示
+V4.3.3 ─────  ✅ Intent 上下文（intent / agent / session trailer + 仪表盘展示）
+V4.3.4 ─────  ✅ 运维加固（日志轮转 / 锁文件时间戳 / preview 分组 / SKILL 规则）
+V4.3.5 ─────  ✅ Summary 增量 diff-tree 修复 + 变更列堆叠布局 + 配色优化
+V4.4.0 ─────  ✅ V4 收官：首次快照 summary + doctor 完整性/retention 检查 + init 升级检测  ← 当前版本
                │
                │  前提：AI 编辑需要更强的追溯 / 恢复 / 查询闭环
                │  前提：多 Agent / 多工具协作成为真实场景
@@ -1022,14 +1032,18 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 
 ## 给用户说的话
 
-### 现在（V4.3）
+### 现在（V4.3.5）
 
 > cursor-guard 已经能保护你的代码，而且越来越聪明。
 > 自动备份、写前快照、确定性恢复——开箱即用。
-> V3 新增：MCP 工具调用（可选）让 AI 操作更稳、更快、更省 token。
-> V4.0 新增：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
-> V4.2 新增：本地 Web 仪表盘——健康、备份、恢复点、诊断一页可见，中英双语自动刷新。
-> V4.3 新增：每次备份带上下文（改了什么、为什么备份、哪个 AI 在操作），在仪表盘可追溯。
+>
+> **V3**：MCP 工具调用（可选）让 AI 操作更稳、更快、更省 token。
+> **V4.0**：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
+> **V4.2**：本地 Web 仪表盘——健康、备份、恢复点、诊断一页可见，中英双语自动刷新。
+> **V4.3.0-4.3.3**：每次备份带上下文（改了什么、为什么备份、哪个 AI 在操作），Intent 意图可追溯。
+> **V4.3.4**：运维加固——日志轮转、锁文件保护、restore 预览分组降低 token 消耗。
+> **V4.3.5**：修复了备份摘要准确性（增量 diff-tree）；仪表盘变更列分层展示，配色全面优化。
+>
 > 经过 4 轮代码审查，138+ 个测试覆盖所有核心路径。
 
 ### 未来
@@ -1059,4 +1073,4 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 ---
 
 *最后更新：2026-03-22*
-*版本：v1.3（V4.3.3 交付，含 Web 仪表盘、备份上下文元数据、Intent 基础）*
+*版本：v1.5（V4.4.0 收官版，含 Web 仪表盘、备份上下文元数据、Intent 基础、增量 summary、doctor 完整性校验、运维加固、UI 优化）*

package/SKILL.md

@@ -147,7 +147,7 @@ When the target file of an edit **falls outside the protected scope**, the agent
 
 > **MCP shortcut**: if `snapshot_now` tool is available, call it with `{ "path": "<project>", "strategy": "git" }` instead of the shell commands below. The tool handles temp index, secrets exclusion, and ref creation internally, and returns `{ "git": { "status": "created", "commitHash": "...", "shortHash": "..." } }`. Report the `shortHash` to the user and proceed.
 >
-> **Best practice — intent context**: Always provide `intent` to describe *what operation you are about to perform and why*. This creates an audit trail so the user can later understand "what was the AI doing when this backup was made". Also pass `message` for the commit subject. Example:
+> **Best practice — intent context**: Before making high-risk changes, call `snapshot_now` with `intent` to directly record what you are about to do. The intent is stored in the Git commit trailer — no intermediary, no file bridge, no concurrency issues. Example:
 > ```json
 > {
 >   "path": "/project",
@@ -158,7 +158,9 @@ When the target file of an edit **falls outside the protected scope**, the agent
 >   "session": "6290c87f"
 > }
 > ```
-> The `intent`, `agent`, and `session` fields are stored as Git commit trailers and displayed in the dashboard restore-point list and detail drawer, forming a complete audit trail per operation.
+> The `intent`, `agent`, and `session` fields are stored as Git commit trailers and displayed in the dashboard restore-point list and detail drawer.
+>
+> **Timeline the user sees**: manual snapshot with intent ("AI准备重构 calculator.js") → auto-backup with file changes ("Modified 2: src/app.js (+15 -3)"). The causal relationship is clear from ordering — the manual snapshot explains WHY, the auto-backup shows WHAT changed.
 
 Use a **temporary index and dedicated ref** so the user's staged/unstaged state is never touched:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.3.5",
+  "version": "4.4.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/bin/cursor-guard-backup.js

@@ -12,6 +12,7 @@ if (args.help || args.h) {
 Options:
   --path <dir>       Project directory to watch (default: current dir)
   --interval <sec>   Override backup interval in seconds
+  --dashboard [port] Start dashboard server alongside watcher (default port: 3120)
   --help, -h         Show this help message
   --version, -v      Show version number`);
   process.exit(0);
@@ -27,5 +28,12 @@ const targetPath = args.path || '.';
 const interval = parseInt(args.interval, 10) || 0;
 const resolved = path.resolve(targetPath);
 
+const opts = {};
+if (args.dashboard !== undefined) {
+  opts.dashboardPort = (typeof args.dashboard === 'string' && /^\d+$/.test(args.dashboard))
+    ? parseInt(args.dashboard, 10)
+    : 3120;
+}
+
 const { runBackup } = require('../lib/auto-backup');
-runBackup(resolved, interval);
+runBackup(resolved, interval, opts);

package/references/bin/cursor-guard-init.js

@@ -56,6 +56,13 @@ console.log(`  Source:  ${skillSource}`);
 console.log(`  Target:  ${skillTarget}`);
 console.log(`  Mode:    ${isGlobal ? 'global (~/.cursor/skills/)' : 'project-local (.cursor/skills/)'}\n`);
 
+// Pre-check: warn if .cursor-guard.json already exists (upgrade scenario)
+const configPath = path.join(projectDir, '.cursor-guard.json');
+if (fs.existsSync(configPath)) {
+  console.log('  NOTE: .cursor-guard.json already exists — your config will be preserved.');
+  console.log('        Only skill files will be updated (upgrade mode).\n');
+}
+
 // Step 1: Copy skill files (excluding node_modules and .git)
 console.log('  [1/4] Copying skill files...');
 if (fs.existsSync(skillTarget)) {

package/references/dashboard/public/app.js

@@ -565,7 +565,9 @@ function relativeTime(ts) {
 /* ── Data fetching ────────────────────────────────────────── */
 
 async function fetchJson(url) {
-  const r = await fetch(url);
+  const sep = url.includes('?') ? '&' : '?';
+  const tokenParam = window.__GUARD_TOKEN__ ? `${sep}token=${window.__GUARD_TOKEN__}` : '';
+  const r = await fetch(url + tokenParam);
   if (!r.ok) throw new Error(`HTTP ${r.status}`);
   return r.json();
 }
@@ -577,10 +579,45 @@ async function loadProjects() {
   }
 }
 
-async function loadPageData() {
+async function loadPageData(opts = {}) {
   if (!state.currentProjectId) return;
-  state.pageData = await fetchJson(`/api/page-data?id=${state.currentProjectId}`);
-  state.lastRefreshAt = Date.now();
+  const id = state.currentProjectId;
+
+  if (opts.progressive) {
+    state.pageData = { dashboard: null, doctor: null, backups: null };
+    const dashPromise = fetchJson(`/api/page-data?id=${id}&scope=dashboard`);
+    const restPromise = Promise.allSettled([
+      fetchJson(`/api/page-data?id=${id}&scope=backups`),
+      fetchJson(`/api/page-data?id=${id}&scope=doctor`),
+    ]);
+
+    const dash = await dashPromise;
+    state.pageData.dashboard = dash.dashboard;
+    state.lastRefreshAt = Date.now();
+    showContent();
+    if (dash.dashboard && !dash.dashboard.error) {
+      renderStrategyBadge(dash.dashboard.strategy);
+      renderOverview(dash.dashboard);
+      renderProtection(dash.dashboard.protectionScope);
+    }
+
+    const [backupsResult, doctorResult] = await restPromise;
+    if (backupsResult.status === 'fulfilled') {
+      state.pageData.backups = backupsResult.value.backups;
+      if (state.pageData.dashboard) {
+        renderBackupsSection(state.pageData.dashboard, Array.isArray(state.pageData.backups) ? state.pageData.backups : []);
+      }
+    }
+    if (doctorResult.status === 'fulfilled') {
+      state.pageData.doctor = doctorResult.value.doctor;
+      if (state.pageData.doctor && !state.pageData.doctor.error) {
+        renderDiagnostics(state.pageData.doctor);
+      }
+    }
+  } else {
+    state.pageData = await fetchJson(`/api/page-data?id=${state.currentProjectId}`);
+    state.lastRefreshAt = Date.now();
+  }
 }
 
 /* ── Refresh ──────────────────────────────────────────────── */
@@ -633,21 +670,18 @@ function renderStrategyBadge(strategy) {
 
 /* ── Rendering: Global states ─────────────────────────────── */
 
-function showLoading() {
-  show($('#loading-state'));
+function showSkeleton() {
   hide($('#error-state'));
-  $$('.screen').forEach(s => hide(s));
+  $$('.screen').forEach(s => show(s));
 }
 
 function showGlobalError(msg) {
-  hide($('#loading-state'));
   show($('#error-state'));
   $$('.screen').forEach(s => hide(s));
   $('#error-message').textContent = msg || t('error.fetchFailed');
 }
 
 function showContent() {
-  hide($('#loading-state'));
   hide($('#error-state'));
   $$('.screen').forEach(s => show(s));
 }
@@ -819,9 +853,10 @@ function translateSummary(raw) {
 }
 
 function formatSummaryCell(b) {
-  const line1 = [];
-  if (b.filesChanged != null) line1.push(`<span class="summary-files">${b.filesChanged} ${t('summary.files')}</span>`);
-  if (b.trigger) line1.push(`<span class="badge badge-trigger">${t('trigger.' + b.trigger)}</span>`);
+  let line1 = '';
+  if (b.filesChanged != null) {
+    line1 = `<div class="summary-meta"><span class="summary-files">${b.filesChanged} ${t('summary.files')}</span></div>`;
+  }
 
   let line2 = '';
   if (b.intent) {
@@ -834,13 +869,12 @@ function formatSummaryCell(b) {
 
   let line3 = '';
   if (b.summary) {
-    const translated = translateSummary(b.summary);
-    const short = translated.length > 90 ? translated.substring(0, 87) + '...' : translated;
-    line3 = `<div class="summary-detail">${esc(short)}</div>`;
+    const categories = b.summary.split('; ').map(s => translateSummary(s));
+    line3 = categories.map(c => `<div class="summary-detail-line">${esc(c)}</div>`).join('');
   }
 
-  if (!line1.length && !line2 && !line3) return '<span class="text-muted text-sm">-</span>';
-  return `<div class="summary-stack">${line1.length ? '<div class="summary-meta">' + line1.join(' ') + '</div>' : ''}${line2}${line3}</div>`;
+  if (!line1 && !line2 && !line3) return '<span class="text-muted text-sm">-</span>';
+  return `<div class="summary-stack">${line1}${line2}${line3}</div>`;
 }
 
 function renderBackupTable(backups) {
@@ -971,7 +1005,10 @@ function openRestoreDrawer(backup) {
   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.message) fields.push({ key: 'drawer.field.message', val: backup.message });
-  if (backup.summary) fields.push({ key: 'drawer.field.summary', val: translateSummary(backup.summary) });
+  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);
@@ -980,7 +1017,10 @@ function openRestoreDrawer(backup) {
     ${fields.map(f => `
       <div class="restore-field">
         <div class="restore-field-label">${t(f.key)}</div>
-        <div class="restore-field-value text-mono">${esc(f.val)}</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>
     `).join('')}
     <div class="restore-actions">
@@ -1123,12 +1163,12 @@ async function init() {
   document.documentElement.lang = state.locale === 'zh-CN' ? 'zh-CN' : 'en';
   document.title = t('app.title');
   updateStaticI18n();
-  showLoading();
+  showSkeleton();
 
   try {
     await loadProjects();
     renderProjectSelect();
-    await loadPageData();
+    await loadPageData({ progressive: true });
     renderAll();
     startRefresh();
   } catch (e) {

package/references/dashboard/public/index.html

@@ -33,12 +33,6 @@
 
   <main id="content">
 
-    <!-- Loading -->
-    <div id="loading-state" class="state-panel">
-      <div class="spinner"></div>
-      <p data-i18n="state.loading">Loading…</p>
-    </div>
-
     <!-- Global Error -->
     <div id="error-state" class="state-panel hidden">
       <div class="error-icon">⚠</div>
@@ -47,35 +41,35 @@
     </div>
 
     <!-- Screen 1: Overview ───────────────────────────────── -->
-    <section id="screen-overview" class="screen hidden">
+    <section id="screen-overview" class="screen">
       <h2 class="section-title" data-i18n="overview.title">Overview</h2>
       <div id="overview-grid" class="card-grid">
-        <div id="card-health" class="card card-health"></div>
-        <div id="card-git-backup" class="card"></div>
-        <div id="card-shadow-backup" class="card"></div>
-        <div id="card-watcher" class="card"></div>
-        <div id="card-alert" class="card"></div>
+        <div id="card-health" class="card card-health"><div class="skeleton-block"></div></div>
+        <div id="card-git-backup" class="card"><div class="skeleton-block"></div></div>
+        <div id="card-shadow-backup" class="card"><div class="skeleton-block"></div></div>
+        <div id="card-watcher" class="card"><div class="skeleton-block"></div></div>
+        <div id="card-alert" class="card"><div class="skeleton-block"></div></div>
       </div>
     </section>
 
     <!-- Screen 2: Backups & Recovery ─────────────────────── -->
-    <section id="screen-backups" class="screen hidden">
+    <section id="screen-backups" class="screen">
       <h2 class="section-title" data-i18n="backups.title">Backups &amp; Recovery</h2>
-      <div id="backup-stats" class="stats-row"></div>
+      <div id="backup-stats" class="stats-row"><div class="skeleton-row"></div></div>
       <div id="backup-filters" class="filter-bar"></div>
-      <div id="backup-table-wrap" class="table-wrap"></div>
+      <div id="backup-table-wrap" class="table-wrap"><div class="skeleton-table"></div></div>
     </section>
 
     <!-- Screen 3: Protection Scope ───────────────────────── -->
-    <section id="screen-protection" class="screen hidden">
+    <section id="screen-protection" class="screen">
       <h2 class="section-title" data-i18n="protection.title">Protection Scope</h2>
-      <div id="protection-content"></div>
+      <div id="protection-content"><div class="skeleton-block"></div></div>
     </section>
 
     <!-- Screen 4: Diagnostics ────────────────────────────── -->
-    <section id="screen-diagnostics" class="screen hidden">
+    <section id="screen-diagnostics" class="screen">
       <h2 class="section-title" data-i18n="diagnostics.title">Diagnostics</h2>
-      <div id="diagnostics-summary"></div>
+      <div id="diagnostics-summary"><div class="skeleton-block"></div></div>
     </section>
 
   </main>

package/references/dashboard/public/style.css

@@ -326,38 +326,64 @@ main {
 .badge-trigger { background: var(--bg-tertiary); color: var(--text-secondary); font-size: 0.7rem; border-color: var(--border-subtle); }
 .badge-intent  { background: var(--blue-bg); color: var(--blue); font-size: 0.7rem; border-color: rgba(59,130,246,.18); max-width: 220px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; display: inline-block; vertical-align: middle; }
 
-.backup-summary-cell { max-width: 400px; }
+.backup-summary-cell { max-width: 420px; min-width: 180px; }
 
-.summary-stack { display: flex; flex-direction: column; gap: 4px; }
-.summary-meta { display: flex; align-items: center; gap: 6px; }
-.summary-files { font-size: 13px; font-weight: 600; color: var(--text-heading); }
+.summary-stack { display: flex; flex-direction: column; gap: 6px; padding: 4px 0; }
+.summary-meta { display: flex; align-items: center; gap: 8px; }
+.summary-files {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--text-heading);
+  font-variant-numeric: tabular-nums;
+}
 .summary-intent {
   font-size: 12px;
   color: var(--blue);
   background: var(--blue-bg);
-  padding: 2px 8px;
-  border-radius: 3px;
-  border-left: 2px solid var(--blue);
+  padding: 4px 10px;
+  border-radius: 4px;
+  border-left: 3px solid var(--blue);
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  max-width: 380px;
+  max-width: 400px;
+  line-height: 1.4;
 }
 .summary-message {
   font-size: 12px;
-  color: var(--text-secondary);
+  color: var(--text-primary);
+  background: var(--bg-tertiary);
+  padding: 3px 8px;
+  border-radius: 3px;
+  border-left: 3px solid var(--text-tertiary);
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  max-width: 380px;
+  max-width: 400px;
+  line-height: 1.4;
 }
-.summary-detail {
-  font-size: 11px;
-  color: var(--text-tertiary);
+.summary-detail-line {
+  font-size: 12px;
+  color: var(--text-secondary);
+  font-family: 'JetBrains Mono', 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+  line-height: 1.5;
+  padding: 1px 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  max-width: 380px;
+  max-width: 400px;
+}
+.summary-detail-line:first-child { padding-top: 2px; }
+
+.summary-pre {
+  font-size: 12px;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  margin: 0;
+  padding: 8px 10px;
+  background: var(--bg-tertiary);
+  border-radius: 4px;
+  border-left: 3px solid var(--blue);
 }
 
 /* ── Stats Row ────────────────────────────────────────────── */
@@ -776,6 +802,54 @@ main {
 
 .icon-spin-active { animation: spin .6s linear infinite; }
 
+/* ── Skeleton loading ────────────────────────────────────── */
+
+@keyframes shimmer {
+  0%   { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+
+.skeleton-block {
+  height: 48px;
+  border-radius: var(--radius-sm);
+  background: linear-gradient(90deg, var(--bg-tertiary) 25%, var(--bg-hover) 50%, var(--bg-tertiary) 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+}
+
+.skeleton-row {
+  display: flex;
+  gap: 12px;
+}
+.skeleton-row::before,
+.skeleton-row::after {
+  content: '';
+  flex: 1;
+  height: 64px;
+  border-radius: var(--radius-sm);
+  background: linear-gradient(90deg, var(--bg-tertiary) 25%, var(--bg-hover) 50%, var(--bg-tertiary) 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+}
+
+.skeleton-table {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px 0;
+}
+.skeleton-table::before,
+.skeleton-table::after {
+  content: '';
+  display: block;
+  height: 36px;
+  border-radius: var(--radius-sm);
+  background: linear-gradient(90deg, var(--bg-tertiary) 25%, var(--bg-hover) 50%, var(--bg-tertiary) 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+}
+.skeleton-table::after { width: 75%; opacity: .6; }
+
 /* ── Utility ──────────────────────────────────────────────── */
 
 .hidden { display: none !important; }

package/references/dashboard/server.js

@@ -2,6 +2,7 @@
 'use strict';
 
 const http = require('http');
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
@@ -12,6 +13,7 @@ const { listBackups } = require('../lib/core/backups');
 const PUBLIC_DIR = path.join(__dirname, 'public');
 const DEFAULT_PORT = 3120;
 const MAX_PORT_RETRIES = 10;
+const ALLOWED_HOSTS = /^(127\.0\.0\.1|localhost)(:\d+)?$/;
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -78,7 +80,7 @@ function forbidden(res) { res.writeHead(403); res.end('Forbidden'); }
 
 /* ── Static file server (strict) ────────────────────────────── */
 
-function serveStatic(reqUrl, res) {
+function serveStatic(reqUrl, res, serverToken) {
   let pathname;
   try { pathname = decodeURIComponent(new URL(reqUrl, 'http://x').pathname); }
   catch { return notFound(res); }
@@ -94,6 +96,23 @@ function serveStatic(reqUrl, res) {
   fs.readFile(resolved, (err, data) => {
     if (err) return notFound(res);
     const ext = path.extname(resolved).toLowerCase();
+
+    // Inject per-process token into index.html so the frontend can authenticate API calls
+    if (pathname === '/index.html' && serverToken) {
+      const html = data.toString('utf-8').replace(
+        '</head>',
+        `<script>window.__GUARD_TOKEN__="${serverToken}";</script></head>`
+      );
+      const buf = Buffer.from(html, 'utf-8');
+      res.writeHead(200, {
+        'Content-Type': MIME[ext] || 'text/html; charset=utf-8',
+        'Content-Length': buf.length,
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+      });
+      return res.end(buf);
+    }
+
     res.writeHead(200, {
       'Content-Type': MIME[ext] || 'application/octet-stream',
       'Content-Length': data.length,
@@ -121,13 +140,21 @@ function handleApi(pathname, query, registry, res) {
   }
 
   if (pathname === '/api/page-data') {
+    const scope = query.get('scope');
     const result = { timestamp: new Date().toISOString() };
-    try { result.dashboard = getDashboard(pp); }
-    catch (e) { result.dashboard = { error: e.message }; }
-    try { result.doctor = runDiagnostics(pp); }
-    catch (e) { result.doctor = { error: e.message }; }
-    try { result.backups = listBackups(pp, { limit: 50 }).sources || []; }
-    catch (e) { result.backups = { error: e.message }; }
+
+    if (!scope || scope === 'dashboard') {
+      try { result.dashboard = getDashboard(pp); }
+      catch (e) { result.dashboard = { error: e.message }; }
+    }
+    if (!scope || scope === 'doctor') {
+      try { result.doctor = runDiagnostics(pp); }
+      catch (e) { result.doctor = { error: e.message }; }
+    }
+    if (!scope || scope === 'backups') {
+      try { result.backups = listBackups(pp, { limit: 50 }).sources || []; }
+      catch (e) { result.backups = { error: e.message }; }
+    }
     return json(res, result);
   }
 
@@ -154,53 +181,93 @@ function handleApi(pathname, query, registry, res) {
 
 /* ── Server ─────────────────────────────────────────────────── */
 
-function main() {
-  const args = parseCliArgs();
-  const registry = buildRegistry(args.paths);
-  let port = args.port;
-  let retries = 0;
-
-  const server = http.createServer((req, res) => {
-    if (req.method !== 'GET') {
-      res.writeHead(405);
-      return res.end('Method Not Allowed');
-    }
-    let parsed;
-    try { parsed = new URL(req.url, `http://${req.headers.host || 'localhost'}`); }
-    catch { return notFound(res); }
-
-    if (parsed.pathname.startsWith('/api/')) {
-      handleApi(parsed.pathname, parsed.searchParams, registry, res);
-    } else {
-      serveStatic(req.url, res);
-    }
-  });
+/**
+ * Start the dashboard HTTP server.
+ * Can be called standalone (CLI) or embedded (from watcher).
+ *
+ * @param {string[]} paths - Project directories to serve
+ * @param {object} [opts]
+ * @param {number} [opts.port=3120] - Starting port
+ * @param {boolean} [opts.silent=false] - Suppress banner output
+ * @returns {Promise<{server: http.Server, port: number, registry: Map}>}
+ */
+function startDashboardServer(paths, opts = {}) {
+  const port = opts.port || DEFAULT_PORT;
+  const silent = opts.silent || false;
+  const registry = buildRegistry(paths);
+  const token = crypto.randomBytes(16).toString('hex');
+
+  return new Promise((resolve, reject) => {
+    let currentPort = port;
+    let retries = 0;
+
+    const server = http.createServer((req, res) => {
+      // DNS rebinding protection: reject unexpected Host headers
+      const host = req.headers.host || '';
+      if (!ALLOWED_HOSTS.test(host)) {
+        res.writeHead(403);
+        return res.end('Forbidden: invalid host');
+      }
+
+      if (req.method !== 'GET') {
+        res.writeHead(405);
+        return res.end('Method Not Allowed');
+      }
+      let parsed;
+      try { parsed = new URL(req.url, `http://${host}`); }
+      catch { return notFound(res); }
+
+      // API endpoints require per-process token
+      if (parsed.pathname.startsWith('/api/')) {
+        const reqToken = parsed.searchParams.get('token');
+        if (reqToken !== token) {
+          res.writeHead(403);
+          return res.end('Forbidden: invalid token');
+        }
+        handleApi(parsed.pathname, parsed.searchParams, registry, res);
+      } else {
+        serveStatic(req.url, res, token);
+      }
+    });
 
-  server.on('error', (err) => {
-    if (err.code === 'EADDRINUSE' && retries < MAX_PORT_RETRIES) {
-      retries++;
-      port++;
-      server.listen(port, '127.0.0.1');
-    } else {
-      console.error('Failed to start:', err.message);
-      process.exit(1);
-    }
-  });
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE' && retries < MAX_PORT_RETRIES) {
+        retries++;
+        currentPort++;
+        server.listen(currentPort, '127.0.0.1');
+      } else {
+        reject(err);
+      }
+    });
 
-  server.on('listening', () => {
-    const addr = server.address();
-    console.log('');
-    console.log('  Cursor Guard Dashboard');
-    console.log('  ─────────────────────────');
-    console.log(`  URL:      http://127.0.0.1:${addr.port}`);
-    console.log(`  Projects: ${registry.size}`);
-    for (const p of registry.values()) {
-      console.log(`    [${p.id}] ${p.name} → ${p._path}`);
-    }
-    console.log('');
+    server.on('listening', () => {
+      const addr = server.address();
+      if (!silent) {
+        console.log('');
+        console.log('  Cursor Guard Dashboard');
+        console.log('  ─────────────────────────');
+        console.log(`  URL:      http://127.0.0.1:${addr.port}`);
+        console.log(`  Projects: ${registry.size}`);
+        for (const p of registry.values()) {
+          console.log(`    [${p.id}] ${p.name} → ${p._path}`);
+        }
+        console.log('');
+      }
+      resolve({ server, port: addr.port, registry });
+    });
+
+    server.listen(currentPort, '127.0.0.1');
   });
+}
+
+/* ── CLI entry ─────────────────────────────────────────────── */
 
-  server.listen(port, '127.0.0.1');
+if (require.main === module) {
+  const args = parseCliArgs();
+  startDashboardServer(args.paths, { port: args.port }).catch(err => {
+    console.error('Failed to start:', err.message);
+    process.exit(1);
+  });
 }
 
-main();
+module.exports = { startDashboardServer };

package/references/lib/auto-backup.js

@@ -25,7 +25,7 @@ function isProcessAlive(pid) {
 
 // ── Main ────────────────────────────────────────────────────────
 
-async function runBackup(projectDir, intervalOverride) {
+async function runBackup(projectDir, intervalOverride, opts = {}) {
   const hasGit = gitAvailable();
   const repo = hasGit && isGitRepo(projectDir);
   const gDir = repo ? getGitDir(projectDir) : null;
@@ -177,6 +177,18 @@ async function runBackup(projectDir, intervalOverride) {
   console.log(color.cyan(`[guard] Watching '${projectDir}' every ${interval}s  (Ctrl+C to stop)`));
   console.log(color.cyan(`[guard] Strategy: ${cfg.backup_strategy}  |  Ref: ${branchRef}  |  Retention: ${cfg.retention.mode}`));
   console.log(color.cyan(`[guard] Log: ${logFilePath}`));
+
+  // Optional embedded dashboard
+  if (opts.dashboardPort) {
+    try {
+      const { startDashboardServer } = require('../dashboard/server');
+      const { port } = await startDashboardServer([projectDir], { port: opts.dashboardPort, silent: true });
+      console.log(color.cyan(`[guard] Dashboard: http://127.0.0.1:${port}`));
+    } catch (e) {
+      console.log(color.yellow(`[guard] Dashboard failed to start: ${e.message}`));
+    }
+  }
+
   console.log('');
 
   // Main loop

package/references/lib/core/backups.js

@@ -313,25 +313,25 @@ function cleanGitRetention(branchRef, gitDirPath, cfg, cwd) {
     return { kept: 0, pruned: 0, mode, rebuilt: false, skipped: true, reason: 'retention disabled' };
   }
 
-  const out = git(['log', branchRef, '--format=%H %aI %cI %s'], { cwd, allowFail: true });
+  const RS = '\x1e', US = '\x1f';
+  const out = git(['log', branchRef, `--format=%H${US}%aI${US}%cI${US}%s${US}%B${RS}`], { cwd, allowFail: true });
   if (!out) {
     return { kept: 0, pruned: 0, mode, rebuilt: false, skipped: true, reason: 'no commits on ref' };
   }
 
-  const lines = out.split('\n').filter(Boolean);
+  const records = out.split(RS).filter(r => r.trim());
   const guardCommits = [];
-  for (const line of lines) {
-    const firstSpace = line.indexOf(' ');
-    const secondSpace = line.indexOf(' ', firstSpace + 1);
-    const thirdSpace = line.indexOf(' ', secondSpace + 1);
-    const hash = line.substring(0, firstSpace);
-    const authorDate = line.substring(firstSpace + 1, secondSpace);
-    const committerDate = line.substring(secondSpace + 1, thirdSpace);
-    const subject = line.substring(thirdSpace + 1);
+  for (const record of records) {
+    const fields = record.split(US);
+    if (fields.length < 5) continue;
+    const hash = fields[0].trim();
+    const authorDate = fields[1].trim();
+    const committerDate = fields[2].trim();
+    const subject = fields[3].trim();
+    const fullBody = fields[4].trim();
     if (subject.startsWith('guard: auto-backup') || subject.startsWith('guard: snapshot')) {
-      guardCommits.push({ hash, authorDate, committerDate, subject });
+      guardCommits.push({ hash, authorDate, committerDate, subject, fullBody });
     }
-    // Non-guard commits are silently skipped; continue scanning older history
   }
 
   const total = guardCommits.length;
@@ -373,7 +373,8 @@ function cleanGitRetention(branchRef, gitDirPath, cfg, cwd) {
   if (!rootTree) {
     return { kept: total, pruned: 0, mode, rebuilt: false, reason: 'could not resolve root tree' };
   }
-  let prevHash = commitTreeWithDate(['commit-tree', rootTree, '-m', toKeep[0].subject], toKeep[0]);
+  const msgOf = (c) => c.fullBody || c.subject;
+  let prevHash = commitTreeWithDate(['commit-tree', rootTree, '-m', msgOf(toKeep[0])], toKeep[0]);
   if (!prevHash) {
     return { kept: total, pruned: 0, mode, rebuilt: false, reason: 'commit-tree failed for root' };
   }
@@ -383,7 +384,7 @@ function cleanGitRetention(branchRef, gitDirPath, cfg, cwd) {
     if (!tree) {
       return { kept: total, pruned: 0, mode, rebuilt: false, reason: `could not resolve tree for commit ${i}` };
     }
-    prevHash = commitTreeWithDate(['commit-tree', tree, '-p', prevHash, '-m', toKeep[i].subject], toKeep[i]);
+    prevHash = commitTreeWithDate(['commit-tree', tree, '-p', prevHash, '-m', msgOf(toKeep[i])], toKeep[i]);
     if (!prevHash) {
       return { kept: total, pruned: 0, mode, rebuilt: false, reason: `commit-tree failed at index ${i}` };
     }

package/references/lib/core/doctor-fix.js

@@ -92,6 +92,11 @@ function runFixes(projectDir, opts = {}) {
         if (!existingIgnore.includes('.cursor-guard-backup')) {
           missingPatterns.push('# cursor-guard shadow copies', '.cursor-guard-backup/', '');
         }
+        const nmEntries = ['node_modules/', '.cursor/skills/**/node_modules/'];
+        const missingNm = nmEntries.filter(e => !existingIgnore.includes(e));
+        if (missingNm.length > 0) {
+          missingPatterns.push('# Dependencies', ...missingNm, '');
+        }
         const missingSecrets = initCfg.secrets_patterns.filter(p => !existingIgnore.includes(p));
         if (missingSecrets.length > 0) {
           missingPatterns.push('# Secrets (cursor-guard defaults)', ...missingSecrets, '');

package/references/lib/core/doctor.js

@@ -92,6 +92,33 @@ function runDiagnostics(projectDir) {
     }
   }
 
+  // 5b. Git retention warning
+  if (repo) {
+    const guardRef = 'refs/guard/auto-backup';
+    const countStr = git(['rev-list', '--count', guardRef], { cwd: projectDir, allowFail: true });
+    const commitCount = countStr ? parseInt(countStr, 10) : 0;
+    if (commitCount > 500 && !cfg.git_retention.enabled) {
+      check('Git retention', 'WARN',
+        `${commitCount} backup commits and git_retention is disabled — set git_retention.enabled=true in .cursor-guard.json to auto-prune old snapshots`);
+    } else if (commitCount > 0 && cfg.git_retention.enabled) {
+      check('Git retention', 'PASS', `${commitCount} commits, auto-prune enabled (${cfg.git_retention.mode}: ${cfg.git_retention.mode === 'days' ? cfg.git_retention.days + 'd' : cfg.git_retention.max_count})`);
+    }
+  }
+
+  // 5c. Backup integrity — verify latest auto-backup tree is reachable
+  if (repo) {
+    const guardRef = 'refs/guard/auto-backup';
+    const latestHash = git(['rev-parse', '--verify', guardRef], { cwd: projectDir, allowFail: true });
+    if (latestHash) {
+      const treeType = git(['cat-file', '-t', `${latestHash}^{tree}`], { cwd: projectDir, allowFail: true });
+      if (treeType === 'tree') {
+        check('Backup integrity', 'PASS', `latest auto-backup commit ${latestHash.substring(0, 7)} tree is valid`);
+      } else {
+        check('Backup integrity', 'FAIL', `latest auto-backup commit ${latestHash.substring(0, 7)} tree is corrupted or unreachable`);
+      }
+    }
+  }
+
   // 6. Guard refs
   if (repo) {
     const refs = git(['for-each-ref', 'refs/guard/', '--format=%(refname)'], { cwd: projectDir, allowFail: true });

package/references/lib/core/restore.js

@@ -11,10 +11,16 @@ const { createGitSnapshot, formatTimestamp, removeSecretsFromIndex } = require('
 // ── Path safety ─────────────────────────────────────────────────
 
 function validateRelativePath(file) {
+  if (!file || typeof file !== 'string') {
+    return { valid: false, error: 'file path is required' };
+  }
   const normalized = path.normalize(file).replace(/\\/g, '/');
   if (path.isAbsolute(normalized) || normalized.startsWith('..')) {
     return { valid: false, error: 'file path must be relative and within project directory' };
   }
+  if (normalized === '.' || normalized === '') {
+    return { valid: false, error: 'file path must target a specific file, not the project root' };
+  }
   return { valid: true, normalized };
 }
 
@@ -66,6 +72,10 @@ function restoreFile(projectDir, file, source, opts = {}) {
     return { status: 'error', restoredFrom: source, error: pathCheck.error };
   }
 
+  if (isToolPath(pathCheck.normalized)) {
+    return { status: 'error', restoredFrom: source, error: `refusing to restore protected path '${pathCheck.normalized}' — use restore_project instead` };
+  }
+
   const preserveCurrent = resolvePreserve(projectDir, opts);
   const repo = isGitRepo(projectDir);
   const result = { restoredFrom: source };
@@ -299,15 +309,29 @@ function executeProjectRestore(projectDir, source, opts = {}) {
       cwd: projectDir, stdio: 'pipe',
     });
 
-    // Restore protected paths from HEAD to prevent tool/skill/config downgrade
+    // Restore protected paths: keep HEAD state, don't let old snapshots resurrect deleted files
     const head = git(['rev-parse', 'HEAD'], { cwd: projectDir, allowFail: true });
     if (head) {
-      for (const p of ['.cursor/', ...GUARD_CONFIGS]) {
-        try {
-          execFileSync('git', ['restore', `--source=HEAD`, '--', p], {
-            cwd: projectDir, stdio: 'pipe',
-          });
-        } catch { /* may not exist in HEAD, that's fine */ }
+      const protectedPatterns = ['.cursor/', ...GUARD_CONFIGS];
+      for (const p of protectedPatterns) {
+        const existsInHead = git(['ls-tree', '--name-only', head, '--', p], { cwd: projectDir, allowFail: true });
+        if (existsInHead) {
+          try {
+            execFileSync('git', ['restore', `--source=HEAD`, '--', p], {
+              cwd: projectDir, stdio: 'pipe',
+            });
+          } catch { /* restore failed, keep whatever is there */ }
+        } else {
+          // HEAD intentionally doesn't have this path — remove if old snapshot resurrected it
+          const fullPath = path.join(projectDir, p);
+          try {
+            if (p.endsWith('/')) {
+              fs.rmSync(fullPath, { recursive: true, force: true });
+            } else {
+              fs.unlinkSync(fullPath);
+            }
+          } catch { /* already gone */ }
+        }
       }
     }
 

package/references/lib/core/snapshot.js

@@ -159,13 +159,39 @@ function createGitSnapshot(projectDir, cfg, opts = {}) {
           const fileName = filePart.split('\t').pop();
           groups[key].push(fileName);
         }
+
+        const numstatOut = git(['diff-tree', '--no-commit-id', '--numstat', '-r', parentTree, newTree], { cwd, 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');
+            if (add !== '-') stats[fname] = `+${add} -${del}`;
+          }
+        }
+
+        function fmtFiles(arr) {
+          return arr.slice(0, 5).map(f => {
+            const s = stats[f];
+            return s ? `${f} (${s})` : f;
+          }).join(', ');
+        }
+
         const parts = [];
-        if (groups.M.length) parts.push(`Modified ${groups.M.length}: ${groups.M.slice(0, 5).join(', ')}`);
-        if (groups.A.length) parts.push(`Added ${groups.A.length}: ${groups.A.slice(0, 5).join(', ')}`);
-        if (groups.D.length) parts.push(`Deleted ${groups.D.length}: ${groups.D.slice(0, 5).join(', ')}`);
-        if (groups.R.length) parts.push(`Renamed ${groups.R.length}: ${groups.R.slice(0, 5).join(', ')}`);
+        if (groups.M.length) parts.push(`Modified ${groups.M.length}: ${fmtFiles(groups.M)}${groups.M.length > 5 ? ', ...' : ''}`);
+        if (groups.A.length) parts.push(`Added ${groups.A.length}: ${fmtFiles(groups.A)}${groups.A.length > 5 ? ', ...' : ''}`);
+        if (groups.D.length) parts.push(`Deleted ${groups.D.length}: ${fmtFiles(groups.D)}${groups.D.length > 5 ? ', ...' : ''}`);
+        if (groups.R.length) parts.push(`Renamed ${groups.R.length}: ${fmtFiles(groups.R)}${groups.R.length > 5 ? ', ...' : ''}`);
         if (parts.length) incrementalSummary = parts.join('; ');
       }
+    } else {
+      const lsInitial = git(['ls-tree', '--name-only', '-r', newTree], { cwd, allowFail: true });
+      if (lsInitial) {
+        const files = lsInitial.split('\n').filter(Boolean);
+        changedCount = files.length;
+        const sample = files.slice(0, 5).join(', ');
+        incrementalSummary = `Added ${files.length}: ${sample}${files.length > 5 ? ', ...' : ''}`;
+      }
     }
 
     // Override context summary with the accurate incremental one