cursor-guard 4.4.0 → 4.4.1

package/README.md

@@ -380,9 +380,11 @@ The skill activates on these signals:
 ### 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
 

package/README.zh-CN.md

@@ -380,9 +380,11 @@ 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
 

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.4.0",
+  "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/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/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,11 +159,29 @@ 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 {