cursor-guard 4.9.1 → 4.9.8

package/SKILL.md

@@ -62,17 +62,24 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
   // "count": keep N newest commits. "days": keep commits from last N days.
   "git_retention": { "enabled": false, "mode": "count", "max_count": 200 },
 
-  // V4: Proactive change-velocity detection (default: on).
-  // When enabled, the watcher monitors file change frequency and raises
-  // alerts when abnormal patterns are detected (e.g. 20+ files in 10s).
-  "proactive_alert": true,
-  "alert_thresholds": {
-    "files_per_window": 20,  // trigger threshold
-    "window_seconds": 10,    // sliding window
-    "cooldown_seconds": 60   // min gap between alerts
-  }
-}
-```
+  // V4: Proactive change-velocity detection (default: on).
+  // When enabled, the watcher monitors file change frequency and raises
+  // alerts when abnormal patterns are detected (e.g. 20+ files in 10s).
+  "proactive_alert": true,
+  "alert_thresholds": {
+    "files_per_window": 20,  // trigger threshold
+    "window_seconds": 10,    // sliding window
+    "cooldown_seconds": 60   // min gap between alerts
+  },
+
+  // V4.9.7: destructive partial-delete pre-warning (default: off).
+  // Triggered when deletion risk is high or whole methods/functions disappear.
+  "enable_pre_warning": false,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": []
+}
+```
 
 **Resolution rules:**
 - `protect` set + `ignore` set → file must match a `protect` pattern AND not match any `ignore` pattern.
@@ -82,10 +89,12 @@ On first trigger in a session, check if the workspace root contains `.cursor-gua
 
 **`secrets_patterns`**: Glob patterns for sensitive files (`.env`, keys, certificates). Matching files are **auto-excluded** from backup commits, even within `protect` scope. Built-in defaults: `.env`, `.env.*`, `*.key`, `*.pem`, `*.p12`, `*.pfx`, `credentials*`. Set this field to override.
 
-**`retention`**: Controls automatic cleanup of old shadow-copy snapshots in `.cursor-guard-backup/`:
-- `"days"` (default): keep snapshots from the last N days (default **30**).
-- `"count"`: keep the N most recent snapshots (default 100).
-- `"size"`: keep total shadow-copy folder under N MB (default 500).
+**`retention`**: Controls automatic cleanup of old shadow-copy snapshots in `.cursor-guard-backup/`:
+- `"days"` (default): keep snapshots from the last N days (default **30**).
+- `"count"`: keep the N most recent snapshots (default 100).
+- `"size"`: keep total shadow-copy folder under N MB (default 500).
+
+**`enable_pre_warning` / `pre_warning_*`**: Optional IDE-side "last brake" for destructive partial deletions. When enabled, the extension scores deletion-heavy edits, removed methods/functions, and suspicious line drops. `popup` interrupts with quick actions, `dashboard` only surfaces the warning in UI/status, and `silent` only records it. Active warnings are exposed through `backup_status` / `dashboard` as `_activePreWarning`.
 
 **If no config file exists**, the agent operates in "protect everything" mode (backward compatible). Mention to the user that they can create `.cursor-guard.json` to narrow scope — see [references/cursor-guard.example.json](references/cursor-guard.example.json).
 
@@ -111,12 +120,13 @@ cursor-guard provides an **MCP server** (`cursor-guard-mcp`) as an optional enha
 | Change-velocity alerts | `alert_status` | manual: check alert file in .git/ or .cursor-guard-backup/ |
 
 **Rules**:
-- MCP results are JSON — parse `status`, `error`, and data fields; do not re-run shell to verify.
-- If an MCP call returns an `error` field, report it to the user and fall back to the shell path for that operation.
-- All Hard Rules (§Hard Rules) still apply regardless of execution path. MCP tools enforce them internally (e.g. `restore_file` creates a pre-restore snapshot by default).
-- If MCP is not configured, the skill works exactly as before — **no degradation**.
-- `doctor_fix` is safe to call — each fix is idempotent. Use `dry_run: true` to preview changes before applying. Typical fixes: create missing config, init git repo, gitignore backup dir, remove stale lock file.
-- `restore_project` with `preview: false` executes a full restore including pre-restore snapshot. Always call with `preview: true` first, show the result to the user, and only execute after explicit confirmation.
+- MCP results are JSON — parse `status`, `error`, and data fields; do not re-run shell to verify.
+- If an MCP call returns an `error` field, report it to the user and fall back to the shell path for that operation.
+- All Hard Rules (§Hard Rules) still apply regardless of execution path. MCP tools enforce them internally (e.g. `restore_file` creates a pre-restore snapshot by default).
+- If MCP is not configured, the skill works exactly as before — **no degradation**.
+- `backup_status` and `dashboard` may include `_activePreWarning`; when present, surface it as an active delete-risk warning before giving the rest of the health summary.
+- `doctor_fix` is safe to call — each fix is idempotent. Use `dry_run: true` to preview changes before applying. Typical fixes: create missing config, init git repo, gitignore backup dir, remove stale lock file.
+- `restore_project` with `preview: false` executes a full restore including pre-restore snapshot. Always call with `preview: true` first, show the result to the user, and only execute after explicit confirmation.
 
 When the target file of an edit **falls outside the protected scope**, the agent:
 - Still applies "Read before Write" (Hard Rule §2).
@@ -603,7 +613,7 @@ Skip the block for unrelated turns.
 - Recovery commands: [references/recovery.md](references/recovery.md)
 - Auto-backup (Node.js core): [references/lib/auto-backup.js](references/lib/auto-backup.js)
 - Guard doctor (Node.js core): [references/lib/guard-doctor.js](references/lib/guard-doctor.js)
-- Core modules: [references/lib/core/](references/lib/core/) (doctor, doctor-fix, snapshot, backups, restore, status, anomaly, dashboard)
+- Core modules: [references/lib/core/](references/lib/core/) (doctor, doctor-fix, snapshot, backups, restore, status, anomaly, pre-warning, dashboard)
 - MCP server: [references/mcp/server.js](references/mcp/server.js) (9 tools: doctor, doctor_fix, backup_status, list_backups, snapshot_now, restore_file, restore_project, dashboard, alert_status)
 - Web dashboard: [references/dashboard/](references/dashboard/) (local read-only web UI — `node references/dashboard/server.js --path <project>`)
 - Shared utilities: [references/lib/utils.js](references/lib/utils.js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.9.1",
+  "version": "4.9.8",
   "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",
@@ -24,7 +24,8 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js"
+    "test": "node references/lib/utils.test.js && node references/lib/core/core.test.js && node references/mcp/mcp.test.js",
+    "release:checklist": "node scripts/print-release-checklist.js"
   },
   "bin": {
     "cursor-guard-init": "references/bin/cursor-guard-init.js",

package/references/config-reference.md

@@ -206,10 +206,71 @@ Thresholds for proactive change-velocity alerts. Only effective when `proactive_
 | `window_seconds` | `integer` | `10` | Sliding time window in seconds for counting file changes |
 | `cooldown_seconds` | `integer` | `60` | Minimum seconds between consecutive alerts to avoid noise |
 
-```json
-"alert_thresholds": {
-  "files_per_window": 20,
-  "window_seconds": 10,
-  "cooldown_seconds": 60
-}
-```
+```json
+"alert_thresholds": {
+  "files_per_window": 20,
+  "window_seconds": 10,
+  "cooldown_seconds": 60
+}
+```
+
+---
+
+## `enable_pre_warning`
+
+- **Type**: `boolean`
+- **Default**: `false`
+
+Enable destructive-edit pre-warning. When enabled, the IDE extension evaluates deletion-heavy edits and removed methods/functions before they quietly land. Active warnings are persisted so `backup_status`, `dashboard`, the sidebar, and the browser dashboard can surface them.
+
+```json
+"enable_pre_warning": true
+```
+
+---
+
+## `pre_warning_threshold`
+
+- **Type**: `integer`
+- **Minimum**: `1`
+- **Maximum**: `100`
+- **Default**: `30`
+
+Risk threshold for triggering a pre-warning. The score is based primarily on deletion ratio, but method/function removal is treated as inherently risky and can still trigger a warning even if the line percentage is below the threshold.
+
+```json
+"pre_warning_threshold": 30
+```
+
+---
+
+## `pre_warning_mode`
+
+- **Type**: `string`
+- **Allowed**: `"popup"` | `"dashboard"` | `"silent"`
+- **Default**: `"popup"`
+
+Controls how the warning is presented inside the IDE extension.
+
+| Value | Description |
+|-------|-------------|
+| `"popup"` | Show an interactive warning with quick actions such as undo / diff review |
+| `"dashboard"` | Do not interrupt editing; highlight the risk in dashboard, sidebar, and status surfaces |
+| `"silent"` | Persist/log the warning without UI interruption |
+
+```json
+"pre_warning_mode": "popup"
+```
+
+---
+
+## `pre_warning_exclude_patterns`
+
+- **Type**: `string[]` (glob patterns)
+- **Default**: not set
+
+Glob patterns that skip pre-warning evaluation. Useful for generated code, migrations, vendored directories, lockfiles, or other files where large deletions are expected and not actionable.
+
+```json
+"pre_warning_exclude_patterns": ["generated/**", "vendor/**"]
+```

package/references/config-reference.zh-CN.md

@@ -206,10 +206,71 @@
 | `window_seconds` | `integer` | `10` | 统计文件变更的滑动时间窗口（秒） |
 | `cooldown_seconds` | `integer` | `60` | 连续告警之间的最小间隔（秒），避免噪声 |
 
-```json
-"alert_thresholds": {
-  "files_per_window": 20,
-  "window_seconds": 10,
-  "cooldown_seconds": 60
-}
-```
+```json
+"alert_thresholds": {
+  "files_per_window": 20,
+  "window_seconds": 10,
+  "cooldown_seconds": 60
+}
+```
+
+---
+
+## `enable_pre_warning`
+
+- **类型**：`boolean`
+- **默认值**：`false`
+
+开启破坏性编辑的事先预警。开启后，IDE 扩展会在高比例删行或方法/函数被移除时先做风险评估；触发后的活跃预警会持久化，`backup_status`、`dashboard`、侧边栏和浏览器仪表盘都能看到。
+
+```json
+"enable_pre_warning": true
+```
+
+---
+
+## `pre_warning_threshold`
+
+- **类型**：`integer`
+- **最小值**：`1`
+- **最大值**：`100`
+- **默认值**：`30`
+
+触发事先预警的风险阈值。评分主要基于删行比例，但“删掉方法/函数”会被视为天然高风险，即使删行占比没到阈值，也可能直接触发预警。
+
+```json
+"pre_warning_threshold": 30
+```
+
+---
+
+## `pre_warning_mode`
+
+- **类型**：`string`
+- **可选值**：`"popup"` | `"dashboard"` | `"silent"`
+- **默认值**：`"popup"`
+
+控制 IDE 扩展里如何呈现预警。
+
+| 值 | 说明 |
+|----|------|
+| `"popup"` | 弹出可交互提醒，支持快速撤销、查看 diff 等动作 |
+| `"dashboard"` | 不打断编辑，只在仪表盘、侧边栏、状态面上高亮风险 |
+| `"silent"` | 仅持久化 / 记录预警，不主动弹出 UI |
+
+```json
+"pre_warning_mode": "popup"
+```
+
+---
+
+## `pre_warning_exclude_patterns`
+
+- **类型**：`string[]`（glob 模式）
+- **默认值**：未设置
+
+跳过事先预警评估的 glob 模式。适合生成代码、迁移脚本、第三方 vendored 目录、锁文件等“经常大段删除但无需人工拦截”的文件。
+
+```json
+"pre_warning_exclude_patterns": ["generated/**", "vendor/**"]
+```

package/references/cursor-guard.example.json

@@ -34,10 +34,14 @@
     "days": 30,
     "max_count": 200
   },
-  "proactive_alert": true,
-  "alert_thresholds": {
-    "files_per_window": 20,
-    "window_seconds": 10,
-    "cooldown_seconds": 60
-  }
-}
+  "proactive_alert": true,
+  "alert_thresholds": {
+    "files_per_window": 20,
+    "window_seconds": 10,
+    "cooldown_seconds": 60
+  },
+  "enable_pre_warning": false,
+  "pre_warning_threshold": 30,
+  "pre_warning_mode": "popup",
+  "pre_warning_exclude_patterns": []
+}

package/references/cursor-guard.schema.json

@@ -36,13 +36,36 @@
       "items": { "type": "string" },
       "description": "Additional glob patterns appended to secrets_patterns (including defaults). Use this to add patterns without losing built-in protection."
     },
-    "pre_restore_backup": {
-      "type": "string",
-      "enum": ["always", "ask", "never"],
-      "default": "always",
-      "description": "'always' (default): automatically preserve current version before every restore. 'ask': prompt the user each time to choose whether to preserve. 'never': skip preservation entirely (not recommended)."
-    },
-    "retention": {
+    "pre_restore_backup": {
+      "type": "string",
+      "enum": ["always", "ask", "never"],
+      "default": "always",
+      "description": "'always' (default): automatically preserve current version before every restore. 'ask': prompt the user each time to choose whether to preserve. 'never': skip preservation entirely (not recommended)."
+    },
+    "enable_pre_warning": {
+      "type": "boolean",
+      "default": false,
+      "description": "Enable pre-warning before risky partial deletions in the IDE extension. Default false for backwards compatibility."
+    },
+    "pre_warning_threshold": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "default": 30,
+      "description": "Deletion risk percentage threshold that triggers a pre-warning. Method/function removal may trigger even when below this threshold."
+    },
+    "pre_warning_mode": {
+      "type": "string",
+      "enum": ["popup", "dashboard", "silent"],
+      "default": "popup",
+      "description": "'popup': show an immediate IDE warning with actions. 'dashboard': mark the project in dashboard/status UI only. 'silent': record the warning in history without surfacing UI alerts."
+    },
+    "pre_warning_exclude_patterns": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Glob patterns excluded from pre-warning checks. Useful for generated files or intentionally volatile code."
+    },
+    "retention": {
       "type": "object",
       "description": "Controls automatic cleanup of old shadow-copy snapshots.",
       "properties": {

package/references/dashboard/public/app.js

@@ -60,9 +60,16 @@ const I18N = {
     'alert.action.deleted':  'Deleted',
     'alert.action.renamed':  'Renamed',
     'alert.breakdown':       '{added} added, {modified} modified, {deleted} deleted',
-    'alert.suggestion':      'Check recent changes and consider creating a manual snapshot',
-    'alert.viewFiles':       'View file details ({n} files)',
-    'modal.alertFiles':      'Alert File Details',
+    'alert.suggestion':      'Check recent changes and consider creating a manual snapshot',
+    'alert.viewFiles':       'View file details ({n} files)',
+    'preWarning.title':      'Pre-Warning',
+    'preWarning.none':       'No destructive edit risk detected',
+    'preWarning.active':     'Delete Risk',
+    'preWarning.file':       'File',
+    'preWarning.risk':       'Risk',
+    'preWarning.methods':    'Methods removed',
+    'preWarning.suggestion': 'Review this deletion before applying or restore from the latest snapshot',
+    'modal.alertFiles':      'Alert File Details',
     'modal.col.restore':     'Restore',
     'modal.copyRestore':     'Copy cmd',
     'modal.restorePreDelete':'Restore pre-delete',
@@ -170,8 +177,9 @@ const I18N = {
     'issue.disk_critically_low':        'Disk space critically low ({gb} GB free)',
     'issue.disk_low':                   'Disk space low ({gb} GB free)',
     'issue.git_backup_stale':           'Last git backup is stale ({rel})',
-    'issue.active_alert':               'Active alert: {type} — {count} files in {window}s',
-    'issue.alert_high_velocity':        'High volume of file changes detected. Consider reviewing recent modifications and creating a manual snapshot.',
+    'issue.active_alert':               'Active alert: {type} — {count} files in {window}s',
+    'issue.pre_warning_active':         'Pre-warning active: {summary}',
+    'issue.alert_high_velocity':        'High volume of file changes detected. Consider reviewing recent modifications and creating a manual snapshot.',
 
     'check.Git installed':              'Git installed',
     'check.Git repository':             'Git repository',
@@ -288,9 +296,16 @@ const I18N = {
     'alert.action.deleted':  '删除',
     'alert.action.renamed':  '重命名',
     'alert.breakdown':       '新增 {added} · 修改 {modified} · 删除 {deleted}',
-    'alert.suggestion':      '建议检查近期变更，并考虑手动创建快照',
-    'alert.viewFiles':       '查看文件详情（{n} 个文件）',
-    'modal.alertFiles':      '告警文件详情',
+    'alert.suggestion':      '建议检查近期变更，并考虑手动创建快照',
+    'alert.viewFiles':       '查看文件详情（{n} 个文件）',
+    'preWarning.title':      '事先预警',
+    'preWarning.none':       '未检测到破坏性编辑风险',
+    'preWarning.active':     '删除风险',
+    'preWarning.file':       '文件',
+    'preWarning.risk':       '风险',
+    'preWarning.methods':    '移除的方法数',
+    'preWarning.suggestion': '建议在应用前检查这次删除，或直接从最新快照恢复',
+    'modal.alertFiles':      '告警文件详情',
     'modal.col.restore':     '恢复',
     'modal.copyRestore':     '复制命令',
     'modal.restorePreDelete':'恢复删除前',
@@ -399,7 +414,8 @@ const I18N = {
     'issue.disk_low':                   '磁盘空间不足（{gb} GB 可用）',
     'issue.git_backup_stale':           '最近 Git 备份已过时（{rel}）',
     'issue.active_alert':               '活跃告警：{type}——{count} 个文件在 {window} 秒内变更',
-    'issue.alert_high_velocity':        '检测到大量文件变更，建议检查最近修改并手动创建快照。',
+    'issue.pre_warning_active':         '事先预警生效：{summary}',
+    'issue.alert_high_velocity':        '检测到大量文件变更，建议检查最近修改并手动创建快照。',
 
     'check.Git installed':              'Git 安装状态',
     'check.Git repository':             'Git 仓库',
@@ -557,8 +573,9 @@ const ISSUE_PATTERNS = [
   { re: /^Disk space low \((.+?) GB free\)$/,                       key: 'issue.disk_low', extract: ['gb'] },
   { re: /^Last git backup is stale \((.+?)\)$/,                     key: 'issue.git_backup_stale', extract: ['rel'] },
   { re: /^Active alert: (.+?) — (\d+) files in (\d+)s$/,           key: 'issue.active_alert', extract: ['type', 'count', 'window'] },
-  { re: /^High volume of file changes/,                             key: 'issue.alert_high_velocity' },
-];
+  { re: /^Pre-warning active: (.+)$/,                               key: 'issue.pre_warning_active', extract: ['summary'] },
+  { re: /^High volume of file changes/,                             key: 'issue.alert_high_velocity' },
+];
 
 function translateIssue(text) {
   for (const p of ISSUE_PATTERNS) {
@@ -850,13 +867,14 @@ function renderAll() {
 
 /* ── Rendering: Overview ──────────────────────────────────── */
 
-function renderOverview(d) {
-  renderHealthCard(d.health);
-  renderGitBackupCard(d.lastBackup);
-  renderShadowBackupCard(d.lastBackup);
-  renderWatcherCard(d.watcher);
-  renderAlertCard(d.alerts);
-}
+function renderOverview(d) {
+  renderHealthCard(d.health);
+  renderGitBackupCard(d.lastBackup);
+  renderShadowBackupCard(d.lastBackup);
+  renderPreWarningCard(d.preWarnings);
+  renderWatcherCard(d.watcher);
+  renderAlertCard(d.alerts);
+}
 
 function renderHealthCard(health) {
   const el = $('#card-health');
@@ -889,9 +907,9 @@ function renderGitBackupCard(lastBackup) {
   `;
 }
 
-function renderShadowBackupCard(lastBackup) {
-  const el = $('#card-shadow-backup');
-  const s = lastBackup?.shadow;
+function renderShadowBackupCard(lastBackup) {
+  const el = $('#card-shadow-backup');
+  const s = lastBackup?.shadow;
   if (!s) {
     el.innerHTML = `<div class="card-label">${t('shadowBackup.title')}</div><div class="card-empty">${t('shadowBackup.none')}</div>`;
     return;
@@ -899,12 +917,40 @@ function renderShadowBackupCard(lastBackup) {
   el.innerHTML = `
     <div class="card-label">${t('shadowBackup.title')}</div>
     <div class="card-value">${esc(relativeTime(s.timestamp))}</div>
-    <div class="card-detail text-muted text-sm">${esc(formatTime(s.timestamp))}</div>
-  `;
-}
-
-function renderWatcherCard(watcher) {
-  const el = $('#card-watcher');
+    <div class="card-detail text-muted text-sm">${esc(formatTime(s.timestamp))}</div>
+  `;
+}
+
+function renderPreWarningCard(preWarnings) {
+  const el = $('#card-prewarning');
+  if (!preWarnings?.active) {
+    el.innerHTML = `
+      <div class="card-label">${t('preWarning.title')}</div>
+      <div class="card-status"><span class="status-dot status-healthy"></span><span>${t('preWarning.none')}</span></div>
+    `;
+    return;
+  }
+
+  const warning = preWarnings.latest || {};
+  const file = warning.file || '-';
+  const risk = warning.riskPercent !== undefined ? `${warning.riskPercent}%` : '-';
+  const methods = warning.removedMethodCount || 0;
+
+  el.innerHTML = `
+    <div class="card-label">${t('preWarning.title')}</div>
+    <div class="card-status"><span class="status-dot status-warning"></span><span class="status-text status-warning">${t('preWarning.active')}</span></div>
+    <div class="alert-details">
+      <div class="alert-detail-row"><span class="alert-detail-label">${t('preWarning.file')}</span><span class="text-mono">${esc(file)}</span></div>
+      <div class="alert-detail-row"><span class="alert-detail-label">${t('preWarning.risk')}</span><span>${esc(risk)}</span></div>
+      ${methods > 0 ? `<div class="alert-detail-row"><span class="alert-detail-label">${t('preWarning.methods')}</span><span>${methods}</span></div>` : ''}
+      <div class="alert-detail-row alert-breakdown text-sm">${esc(warning.summary || t('preWarning.suggestion'))}</div>
+      <div class="alert-detail-row alert-suggestion text-sm text-muted">${t('preWarning.suggestion')}</div>
+    </div>
+  `;
+}
+
+function renderWatcherCard(watcher) {
+  const el = $('#card-watcher');
   let st = 'stopped';
   if (watcher?.running) st = 'running';
   else if (watcher?.stale) st = 'stale';

package/references/dashboard/public/index.html

@@ -44,13 +44,14 @@
     <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 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>
+      <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-prewarning" 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">

package/references/lib/auto-backup.js

@@ -22,6 +22,45 @@ function isProcessAlive(pid) {
   catch { return false; }
 }
 
+/**
+ * Ignore fs.watch events that originate inside the Git directory (including our snapshots).
+ * This is the **full** fix for the feedback loop: snapshot writes under `.git/` must never
+ * schedule another backup. No time-based cooldown — rely entirely on path semantics.
+ *
+ * On Windows, `filename` is often relative to the repo root but WITHOUT a `.git/` prefix
+ * (e.g. `HEAD`, `objects/ab/...`, `refs/guard/auto-backup`).
+ */
+const GIT_ONLY_TOP_NAMES = new Set([
+  'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD', 'COMMIT_EDITMSG', 'index', 'packed-refs',
+  'cursor-guard-index', 'cursor-guard-index.lock', 'cursor-guard.lock',
+  'refs', 'objects', 'logs', 'hooks', 'info', 'worktrees', 'modules', 'description',
+]);
+
+function shouldIgnoreFsWatchEvent(projectDir, filename, realGitDir) {
+  if (!filename) return true;
+  const norm = String(filename).replace(/\\/g, '/');
+  if (norm.startsWith('.git/') || norm === '.git') return true;
+  if (norm.startsWith('.cursor-guard-backup')) return true;
+
+  const gitRoot = realGitDir || path.join(projectDir, '.git');
+
+  try {
+    if (norm.includes('/') || GIT_ONLY_TOP_NAMES.has(norm)) {
+      const candidate = path.join(gitRoot, norm);
+      if (fs.existsSync(candidate)) return true;
+    }
+  } catch { /* ignore */ }
+
+  try {
+    const abs = path.resolve(projectDir, filename);
+    const gitDirAbs = path.resolve(gitRoot);
+    const rel = path.relative(gitDirAbs, abs);
+    if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) return true;
+  } catch { /* ignore */ }
+
+  return false;
+}
+
 // ── Main ────────────────────────────────────────────────────────
 
 async function runBackup(projectDir, intervalOverride, opts = {}) {
@@ -323,9 +362,8 @@ async function runBackup(projectDir, intervalOverride, opts = {}) {
 
     watcher.on('change', (_eventType, filename) => {
       if (!filename) return;
+      if (shouldIgnoreFsWatchEvent(projectDir, filename, gDir)) return;
       const f = filename.replace(/\\/g, '/');
-      if (f.startsWith('.git/') || f.startsWith('.git\\')) return;
-      if (f.startsWith('.cursor-guard-backup')) return;
       if (f === '.cursor-guard.json') {
         hotReloadConfig();
         return;