cursor-guard 4.3.2 → 4.3.4

package/README.md

@@ -377,6 +377,20 @@ The skill activates on these signals:
 
 ## Changelog
 
+### v4.3.4
+
+- **Improve**: Log rotation — `backup.log` now rotates at 1MB, keeping up to 3 old files (`backup.log.1`, `.2`, `.3`). Rotation runs on watcher startup and every 100 writes
+- **Improve**: Watcher single-instance protection — lock file now includes startup timestamp; locks older than 24h are auto-cleaned even if PID check is unreliable on Windows
+- **Improve**: `previewProjectRestore` output grouped — protected paths (`.cursor/`, `.gitignore`, `.cursor-guard.json`) summarized as `protectedPaths: { count: N }` instead of listing thousands of individual files, drastically reducing token cost
+- **Improve**: SKILL.md Hard Rule #15 — agents must commit skill files after upgrade to ensure `restore_project` HEAD protection works correctly
+
+### v4.3.3
+
+- **Feature**: Intent context for snapshots — `snapshot_now` now accepts `intent`, `agent`, and `session` parameters, stored as Git commit trailers to form an audit trail per operation
+- **Feature**: Dashboard displays intent badge in backup table and full intent/agent/session fields in restore-point drawer
+- **Improve**: `parseCommitTrailers` refactored to a data-driven map, supporting all 6 trailer fields (Files-Changed, Summary, Trigger, Intent, Agent, Session)
+- **Improve**: SKILL.md updated to guide AI agents to pass `intent` describing the operation about to happen
+
 ### v4.3.2
 
 - **Fix**: `cursor-guard-init` now adds `node_modules/` (root-level) to `.gitignore` — prevents `git add -A` from scanning thousands of npm dependency files after `npm install cursor-guard --save-dev`

package/README.zh-CN.md

@@ -377,6 +377,20 @@ node references\dashboard\server.js --path "D:\MyProject"
 
 ## 更新日志
 
+### v4.3.4
+
+- **改进**：日志轮转——`backup.log` 超过 1MB 自动轮转，保留最近 3 个旧文件。watcher 启动时和每 100 次写入时检查
+- **改进**：Watcher 单实例保护——锁文件新增启动时间戳；超过 24 小时的锁即使 PID 检查不可靠（Windows）也自动清理
+- **改进**：`previewProjectRestore` 分组输出——受保护路径（`.cursor/`、`.gitignore`、`.cursor-guard.json`）汇总为 `protectedPaths: { count: N }`，不再逐一列出数千个文件，大幅降低 token 消耗
+- **改进**：SKILL.md 硬规则 #15——升级后 Agent 必须提交 skill 文件，确保 `restore_project` 的 HEAD 保护机制生效
+
+### v4.3.3
+
+- **功能**：快照意图上下文——`snapshot_now` 新增 `intent`（操作意图）、`agent`（AI 模型）、`session`（会话 ID）参数，作为 Git commit trailer 存储，形成按操作事件的审计链
+- **功能**：仪表盘备份表格显示意图徽章，恢复点抽屉完整展示 intent/agent/session 字段
+- **改进**：`parseCommitTrailers` 重构为数据驱动映射表，支持全部 6 个 trailer 字段
+- **改进**：SKILL.md 更新指引，要求 AI agent 在调用 `snapshot_now` 时传入 `intent` 描述即将执行的操作
+
 ### v4.3.2
 
 - **修复**：`cursor-guard-init` 现在会将根目录 `node_modules/` 加入 `.gitignore`——防止 `npm install cursor-guard --save-dev` 后 `git add -A` 扫描数千个依赖文件导致极度缓慢

package/ROADMAP.md

@@ -3,8 +3,8 @@
 > 本文档描述 cursor-guard 从 V2 到 V7 的长期演进方向。
 > 每一代向下兼容，低版本功能永远不废弃。
 >
-> **当前版本**：`V4.0.0`  
-> **文档状态**：`V2` ~ `V4.0` 已实施，`V5+` 规划中
+> **当前版本**：`V4.3.3`  
+> **文档状态**：`V2` ~ `V4.3` 已实施（含 V5 intent 基础），`V5` 主体规划中
 
 ## 阅读导航
 
@@ -20,8 +20,8 @@
 |---|---|---|---|
 | `V2` | 能用 | Skill + Script | "AI 弄丢代码能恢复" |
 | `V3` | 更稳 | + Core 抽取 + 可选 MCP | "恢复操作更标准、更省 token" |
-| `V4` | 更聪明 | + 主动检测 + 可观测 | "cursor-guard 会主动提醒你" ✅ |
-| `V5` | 成闭环 | + 变更控制层 | "AI 代码变更可预防、可追溯、可按事件恢复" |
+| `V4` | 更聪明 | + 主动检测 + 可观测 + Web 仪表盘 + Intent 基础 | "cursor-guard 会主动提醒你，还能看到为什么备份" ✅ |
+| `V5` | 成闭环 | + 变更控制层 | "AI 代码变更可预防、可追溯、可按事件恢复"（intent 基础已在 V4.3 落地） |
 | `V6` | 成标准 | + 开放协议 + 团队工作流 | "把 AI 代码变更安全做成跨工具标准" |
 | `V7` | 可证明 | + 可验证信任 + 治理层 | "能证明安全流程被执行了" |
 
@@ -64,7 +64,9 @@ V2-V3 的目标是让用户"离不开"，V6-V7 的目标是让行业"绕不开"
 | `Node Core` | `V3.0` ✅ 已完成 | 6 个模块：doctor / doctor-fix / snapshot / backups / restore / status | 否 |
 | `MCP Server` | `V3.1-V4.0` ✅ 已完成 | 9 个工具，Agent 标准调用入口，结构化 JSON 返回 | 否 |
 | `智能提醒 / 可观测` | `V4.0` ✅ 已完成 | 主动发现风险、汇总健康状态（anomaly + dashboard） | 否 |
-| `变更控制层` | `V5` 规划 | 覆盖编辑意图、冲突告警、影响半径、审计事件、按事件恢复 | 否 |
+| `Web 仪表盘` | `V4.2` ✅ 已完成 | 本地只读 Web UI，备份/恢复点/诊断/保护范围，中英双语 | 否 |
+| `备份上下文 + Intent` | `V4.3` ✅ 已完成 | 结构化 commit trailer（Files-Changed/Summary/Trigger/Intent/Agent/Session），仪表盘可追溯 | 否 |
+| `变更控制层` | `V5` 规划（intent 基础已在 V4.3 落地） | 覆盖编辑意图、冲突告警、影响半径、审计事件、按事件恢复 | 否 |
 | `开放协议 / 团队工作流` | `V6` 规划 | 把变更控制能力提炼成跨工具协议、适配器和 CI 查询入口 | 否 |
 | `治理 / 可验证层` | `V7` 规划 | 让“是否走过安全流程”变成可以证明、可以审计、可以验证的事实 | 否 |
 
@@ -440,10 +442,25 @@ V4 经过 4 轮系统性代码审查，修复了以下关键问题：
 | 三审 | 4 项 | `doctor-fix.js` stale-lock PID 正则修正（`pid=` 格式）；Git pre-restore ref 加毫秒防碰撞；非 Git pre-restore shadow 同步加碰撞检测；`doctor.js` shadow 目录正则支持毫秒后缀 |
 | 四审 | 3+2 项 | `createGitSnapshot` protect basename 语义对齐（`git add -A` + `matchesAny` 裁剪替代 `git add -- <pattern>`）；`unquoteGitPath()` 反解 C-quoted 路径（支持 UTF-8 octal）；pre-restore ref / shadow snapshot 碰撞重试循环（最多 1000 次）；`previewProjectRestore` 正确解析 rename/copy 条目 |
 
+### V4.x 增量（全部已完成 ✅）
+
+| 版本 | 新增 | 状态 |
+|---|---|---|
+| V4.1 | 用户反馈修复：fileCount 精度、安装流程、doctor MCP 检测、PowerShell 兼容 | ✅ |
+| V4.2.0 | **Web 仪表盘**：本地只读 Web UI，健康总览、备份表格、恢复点抽屉、诊断、保护范围。中英双语、自动刷新、多项目支持 | ✅ |
+| V4.2.1 | 代码审查修复：`t()` replaceAll、未用导入清理、过滤栏补全、跨平台 shell 兼容、去重 | ✅ |
+| V4.2.2 | `restore_project` 保护 `.cursor-guard.json`；init 提示 `git commit` | ✅ |
+| V4.3.0 | **备份上下文元数据**：Git commit 结构化 trailer（Files-Changed / Summary / Trigger），仪表盘"变更"列 | ✅ |
+| 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.2 的 Web 仪表盘最初在 V4.0 规划中标记为"不做"，但用户需求明确后实施。事实证明只读仪表盘投入产出比合理，且不违反安全原则。
+
 ### V4 不做的事
 
 - 不做自动恢复（恢复永远需要人确认，这是产品底线）
-- 不做 Web 仪表盘
+- ~~不做 Web 仪表盘~~ → V4.2 已实施（只读、本地、零依赖）
 - 不做云端同步
 
 ### 进入 V5 的衡量标准
@@ -494,10 +511,10 @@ V5 不是"三个方向选一个"，而是把下面这条链路做完整：
 
 | 模块 / 能力 | AI 要做什么 | 建议产物 | 完成标准 |
 |---|---|---|---|
-| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件 |
+| `intent registry` | 在高风险写入前注册编辑意图，记录 agent、会话、工作区、分支、目标文件、风险级别 | `core/intent.*` 或同等模块 | 能列出活跃会话，能释放会话，能查到谁准备改哪个文件。**基础版已在 V4.3.3 落地**：`snapshot_now` 支持 `intent` / `agent` / `session` 参数，存储为 Git commit trailer，仪表盘可展示 |
 | `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 / 时间 / 风险级别查询 |
+| `audit store` | 以 append-only 方式保存 AI 编辑事件 | 默认本地 `JSONL`；后续可升级 `SQLite` | 能按文件 / 会话 / agent / 时间 / 风险级别查询。**雏形已在 V4.3.0-V4.3.3 落地**：审计元数据通过 Git commit trailer 持久化，`listBackups` 可按 trigger/intent/agent/session 解析 |
 | `restore by event` | 允许从一条审计事件直接跳转并执行恢复 | `restore_from_event` | 给定 `event_id` 可以定位 `before_ref` 或 `restore_ref` |
 | `impact set` | 为高风险编辑记录受影响文件 / 符号 / 测试集合 | `impact_set` 字段 | 查询事件时能看到"这次改动可能波及哪里" |
 | `MCP / CLI surface` | 暴露最小可用接口给 Agent 和终端 | `register_intent` / `list_active_intents` / `audit_query` / `get_event` / `restore_from_event` | AI 不需要拼复杂 shell，就能完成查询与恢复 |
@@ -935,8 +952,8 @@ V7.2  完整 attestation（安全操作证明链）
 
 | | V2 | V3 | V4 | V5 | V6 | V7 |
 |---|---|---|---|---|---|---|
-| **一句话** | 能恢复 | 更稳更省 | 主动提醒 | 变更闭环 | 跨工具标准 | 可证明 |
-| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
+| **一句话** | 能恢复 | 更稳更省 | 主动提醒 + 可观测 + Intent | 变更闭环 | 跨工具标准 | 可证明 |
+| **核心架构** | Skill + Script | + Core + MCP | + 智能检测 + Web 仪表盘 + Intent 基础 | + 变更控制层 | + 开放协议 + 适配器 | + 治理层 |
 | **Agent 调用** | 拼 shell | 优先 MCP | MCP + 主动建议 | MCP + 意图 / 审计 / 恢复 | 标准接口 + 适配器 | 标准接口 + 审计 |
 | **安装门槛** | 最低 | 不变 | 不变 | 略增 | 看具体实现 | 看具体实现 |
 | **适合谁** | 所有人 | 所有人 | 所有人 | 重度 AI 用户 + 团队试点 | 工具开发者 + 团队 | 企业 + 合规场景 |
@@ -957,8 +974,11 @@ V3.4  ──────  ✅ MCP 自检
                │
                │  前提：MCP 调用成功率 > 95%，token 消耗可观测下降
                ▼
-V4.0  ──────  ✅ 智能恢复建议 + 备份健康看板 + 4 轮代码审查加固（138 测试）  ← 当前版本
-V4.x  ──────  候选支线（完整性校验 / 多项目概览）
+V4.0  ──────  ✅ 智能恢复建议 + 备份健康看板 + 4 轮代码审查加固（138 测试）
+V4.1  ──────  ✅ 用户反馈修复
+V4.2  ──────  ✅ Web 仪表盘（只读、双语、多项目）+ 代码审查修复
+V4.3  ──────  ✅ 备份上下文元数据 + Intent 上下文 + restore 安全加固  ← 当前版本
+V4.x  ──────  候选支线（完整性校验 / 更丰富的审计查询）
                │
                │  前提：AI 编辑需要更强的追溯 / 恢复 / 查询闭环
                │  前提：多 Agent / 多工具协作成为真实场景
@@ -1002,13 +1022,15 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 
 ## 给用户说的话
 
-### 现在（V4）
+### 现在（V4.3）
 
 > cursor-guard 已经能保护你的代码，而且越来越聪明。
 > 自动备份、写前快照、确定性恢复——开箱即用。
 > V3 新增：MCP 工具调用（可选）让 AI 操作更稳、更快、更省 token。
-> V4 新增：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
-> 经过 4 轮代码审查，138 个测试覆盖所有核心路径。
+> V4.0 新增：系统会主动监测异常变更并提醒你，一个 `dashboard` 就能看全局健康状态。
+> V4.2 新增：本地 Web 仪表盘——健康、备份、恢复点、诊断一页可见，中英双语自动刷新。
+> V4.3 新增：每次备份带上下文（改了什么、为什么备份、哪个 AI 在操作），在仪表盘可追溯。
+> 经过 4 轮代码审查，138+ 个测试覆盖所有核心路径。
 
 ### 未来
 
@@ -1027,7 +1049,7 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 | 自动恢复（无人确认） | 恢复操作必须有人确认，这是产品底线 |
 | 自动 push 到远程 | 本地优先，push 需用户明确指令 |
 | 云端备份服务 | cursor-guard 的定位是本地安全网 |
-| Web 仪表盘 | 投入产出比不合理 |
+| ~~Web 仪表盘~~ | ~~投入产出比不合理~~ → V4.2 已实施只读仪表盘（本地、零依赖、不执行写操作） |
 | 取代 Git | cursor-guard 是 Git 的增强，不是替代 |
 | AI 行为限制 | cursor-guard 是安全网，不是笼子 |
 | 多 IDE 全面适配 | 聚焦 Cursor，其他 IDE 由社区或 V6 协议解决 |
@@ -1036,5 +1058,5 @@ V7 的"可验证治理"是这条产品线的逻辑终点——该保护的都保
 
 ---
 
-*最后更新：2026-03-21*
-*版本：v1.2（V4.0 最终交付，含 4 轮代码审查加固）*
+*最后更新：2026-03-22*
+*版本：v1.3（V4.3.3 交付，含 Web 仪表盘、备份上下文元数据、Intent 基础）*

package/SKILL.md

@@ -147,14 +147,18 @@ 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 — descriptive messages**: Always provide a meaningful `message` parameter that describes *why* this snapshot is being created and *what* changes are at risk. This message appears in the dashboard restore-point list, helping users identify which snapshot to restore from. Example:
+> **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:
 > ```json
 > {
 >   "path": "/project",
 >   "strategy": "git",
->   "message": "guard: before refactoring auth middleware — moving session logic from app.js to middleware/auth.js"
+>   "message": "guard: before refactoring auth middleware",
+>   "intent": "用户要求将 app.js 中的 session 逻辑拆分到 middleware/auth.js，涉及 3 个函数重写",
+>   "agent": "claude-4-opus",
+>   "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.
 
 Use a **temporary index and dedicated ref** so the user's staged/unstaged state is never touched:
 
@@ -579,6 +583,7 @@ Skip the block for unrelated turns.
 12. **Concurrent agents**: if multiple Agent threads are active, warn the user to avoid simultaneous writes to the same file. Snapshots cannot prevent race conditions between parallel agents.
 13. **Preservation must not pollute** — all pre-restore backups use temp index + dedicated ref (`refs/guard/pre-restore`). The user's staging area, working tree, and commit history on their branch are never modified by the preservation process.
 14. **Do not restore `.cursor/` directory** — `.cursor/skills/`, `.cursor/rules/`, and `.cursor/mcp.json` are tool infrastructure, not project code. `restore_project` automatically protects this directory. Never include `.cursor/` in manual restore commands unless the user explicitly requests it. Restoring `.cursor/skills/cursor-guard/` would downgrade the protection tool itself.
+15. **Commit skill files after upgrade** — after running `cursor-guard-init` or upgrading the skill, immediately commit `.cursor/skills/cursor-guard/` and `.cursor-guard.json` to HEAD (`git add .cursor/ .cursor-guard.json && git commit -m "chore: upgrade cursor-guard"`). This ensures `restore_project`'s HEAD protection mechanism can preserve the current skill version. Without this commit, a restore could revert the skill to an older version.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-guard",
-  "version": "4.3.2",
+  "version": "4.3.4",
   "description": "Protects code from accidental AI overwrite or deletion in Cursor IDE — mandatory pre-write snapshots, review-before-apply, local Git safety net, and deterministic recovery. | 保护代码免受 Cursor AI 代理意外覆写或删除——强制写前快照、预览再执行、本地 Git 安全网、确定性恢复。",
   "keywords": [
     "cursor",

package/references/dashboard/public/app.js

@@ -100,6 +100,9 @@ const I18N = {
     'summary.deleted':      'Deleted',
     'summary.renamed':      'Renamed',
     'summary.files':        'files',
+    'drawer.field.intent':  'Intent',
+    'drawer.field.agent':   'Agent',
+    'drawer.field.session': 'Session',
 
     'error.fetchFailed':    'Failed to fetch data',
     'error.sectionFailed':  'This section failed to load',
@@ -278,6 +281,9 @@ const I18N = {
     'summary.deleted':      '删除',
     'summary.renamed':      '重命名',
     'summary.files':        '个文件',
+    'drawer.field.intent':  '操作意图',
+    'drawer.field.agent':   'AI 模型',
+    'drawer.field.session': '会话 ID',
 
     'error.fetchFailed':    '数据拉取失败',
     'error.sectionFailed':  '此区块加载失败',
@@ -821,7 +827,10 @@ function formatSummaryCell(b) {
     const short = translated.length > 80 ? translated.substring(0, 77) + '...' : translated;
     parts.push(`<span class="text-muted text-sm">${esc(short)}</span>`);
   }
-  if (b.message && !b.message.startsWith('guard:')) {
+  if (b.intent) {
+    const intentShort = b.intent.length > 60 ? b.intent.substring(0, 57) + '...' : b.intent;
+    parts.push(`<span class="badge badge-intent">${esc(intentShort)}</span>`);
+  } else if (b.message && !b.message.startsWith('guard:')) {
     const msgShort = b.message.length > 50 ? b.message.substring(0, 47) + '...' : b.message;
     parts.push(`<span class="text-muted text-sm">${esc(msgShort)}</span>`);
   }
@@ -952,6 +961,9 @@ function openRestoreDrawer(backup) {
   if (backup.ref) fields.push({ key: 'drawer.field.ref', val: backup.ref });
   if (backup.commitHash) fields.push({ key: 'drawer.field.hash', val: backup.commitHash });
   if (backup.path) fields.push({ key: 'drawer.field.path', val: backup.path });
+  if (backup.intent) fields.push({ key: 'drawer.field.intent', val: backup.intent });
+  if (backup.agent) fields.push({ key: 'drawer.field.agent', val: backup.agent });
+  if (backup.session) fields.push({ key: 'drawer.field.session', val: backup.session });
   if (backup.message) fields.push({ key: 'drawer.field.message', val: backup.message });
   if (backup.summary) fields.push({ key: 'drawer.field.summary', val: translateSummary(backup.summary) });
 

package/references/dashboard/public/style.css

@@ -248,9 +248,11 @@ main {
 .badge-shadow  { background: var(--amber-bg); color: var(--amber); }
 .badge-pre     { background: var(--purple-bg); color: var(--purple); }
 .badge-trigger { background: var(--bg-tertiary); color: var(--text-secondary); font-size: 0.7rem; }
+.badge-intent  { background: var(--blue-bg); color: var(--blue); font-size: 0.7rem; max-width: 220px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; display: inline-block; vertical-align: middle; }
 
-.backup-summary-cell { max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.backup-summary-cell { max-width: 340px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .backup-summary-cell .badge-trigger { margin-right: 4px; }
+.backup-summary-cell .badge-intent  { margin-left: 4px; }
 .backup-summary-cell .text-sm { font-size: 0.75rem; }
 
 /* ── Stats Row ────────────────────────────────────────────── */

package/references/lib/auto-backup.js

@@ -72,24 +72,39 @@ async function runBackup(projectDir, intervalOverride) {
   // Ensure backup dir
   fs.mkdirSync(backupDir, { recursive: true });
 
-  // Lock file with stale detection
+  // Lock file with stale detection (PID + age)
+  const LOCK_MAX_AGE_MS = 24 * 60 * 60 * 1000;
   if (fs.existsSync(lockFile)) {
     let stale = false;
+    let reason = '';
     try {
       const content = fs.readFileSync(lockFile, 'utf-8');
       const pidMatch = content.match(/pid=(\d+)/);
-      if (pidMatch) {
-        const oldPid = parseInt(pidMatch[1], 10);
-        if (!isProcessAlive(oldPid)) {
+      const startedMatch = content.match(/started=(.+)/);
+      const oldPid = pidMatch ? parseInt(pidMatch[1], 10) : null;
+      const startedAt = startedMatch ? Date.parse(startedMatch[1]) : NaN;
+
+      if (oldPid && !isProcessAlive(oldPid)) {
+        stale = true;
+        reason = `pid ${oldPid} not running`;
+      } else if (!isNaN(startedAt) && Date.now() - startedAt > LOCK_MAX_AGE_MS) {
+        stale = true;
+        reason = `lock age > 24h (started ${startedMatch[1]})`;
+      } else if (!oldPid) {
+        const stat = fs.statSync(lockFile);
+        if (Date.now() - stat.mtimeMs > LOCK_MAX_AGE_MS) {
           stale = true;
-          console.log(color.yellow(`[guard] Stale lock detected (pid ${oldPid} not running). Cleaning up.`));
-          fs.unlinkSync(lockFile);
+          reason = 'lock file too old (no PID, mtime > 24h)';
         }
       }
     } catch { /* ignore */ }
-    if (!stale) {
+    if (stale) {
+      console.log(color.yellow(`[guard] Stale lock detected (${reason}). Cleaning up.`));
+      try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+    } else {
       console.log(color.red(`[guard] ERROR: Lock file exists (${lockFile}).`));
-      console.log(color.red('  If no other instance is running, delete it and retry.'));
+      console.log(color.red('  Another watcher instance may be running.'));
+      console.log(color.red('  If no other instance is running, delete the lock file and retry.'));
       process.exit(1);
     }
   }

package/references/lib/core/backups.js

@@ -41,15 +41,24 @@ function entryToMs(entry) {
   return d ? d.getTime() : 0;
 }
 
+const TRAILER_MAP = {
+  'Files-Changed': { key: 'filesChanged', parse: v => parseInt(v, 10) },
+  'Summary':       { key: 'summary' },
+  'Trigger':       { key: 'trigger' },
+  'Intent':        { key: 'intent' },
+  'Agent':         { key: 'agent' },
+  'Session':       { key: 'session' },
+};
+
 function parseCommitTrailers(body) {
   if (!body) return {};
   const result = {};
+  const pattern = new RegExp(`^(${Object.keys(TRAILER_MAP).join('|')}):\\s*(.+)$`);
   for (const line of body.split('\n')) {
-    const m = line.match(/^(Files-Changed|Summary|Trigger):\s*(.+)$/);
+    const m = line.match(pattern);
     if (m) {
-      const key = m[1] === 'Files-Changed' ? 'filesChanged'
-        : m[1] === 'Summary' ? 'summary' : 'trigger';
-      result[key] = key === 'filesChanged' ? parseInt(m[2], 10) : m[2];
+      const def = TRAILER_MAP[m[1]];
+      result[def.key] = def.parse ? def.parse(m[2]) : m[2];
     }
   }
   return result;

package/references/lib/core/restore.js

@@ -170,7 +170,7 @@ function restoreFile(projectDir, file, source, opts = {}) {
  *
  * @param {string} projectDir
  * @param {string} source - Commit hash or ref
- * @returns {{ status: 'ok'|'error', files?: Array<{path: string, change: 'modified'|'added'|'deleted'}>, totalChanged?: number, error?: string }}
+ * @returns {{ status: 'ok'|'error', files?: Array<{path: string, change: string}>, protectedPaths?: {count: number, note?: string}, totalChanged?: number, error?: string }}
  */
 function previewProjectRestore(projectDir, source) {
   if (!isGitRepo(projectDir)) {
@@ -218,13 +218,27 @@ function previewProjectRestore(projectDir, source) {
       }
     }
 
+    const protectedFiles = [];
+    const projectFiles = [];
     for (const f of files) {
       if (isToolPath(f.path)) {
-        f.warning = 'protected path — will be preserved from HEAD to prevent tool/config downgrade';
+        protectedFiles.push(f);
+      } else {
+        projectFiles.push(f);
       }
     }
 
-    return { status: 'ok', files, totalChanged: files.length };
+    return {
+      status: 'ok',
+      files: projectFiles,
+      protectedPaths: {
+        count: protectedFiles.length,
+        note: protectedFiles.length > 0
+          ? 'these paths (.cursor/, .cursor-guard.json, .gitignore) will be preserved from HEAD'
+          : undefined,
+      },
+      totalChanged: files.length,
+    };
   } catch (e) {
     return { status: 'error', error: e.message };
   }

package/references/lib/core/snapshot.js

@@ -65,6 +65,9 @@ function buildCommitMessage(ts, opts) {
   if (ctx.changedFileCount != null) trailers.push(`Files-Changed: ${ctx.changedFileCount}`);
   if (ctx.summary) trailers.push(`Summary: ${ctx.summary}`);
   if (ctx.trigger) trailers.push(`Trigger: ${ctx.trigger}`);
+  if (ctx.intent) trailers.push(`Intent: ${ctx.intent}`);
+  if (ctx.agent) trailers.push(`Agent: ${ctx.agent}`);
+  if (ctx.session) trailers.push(`Session: ${ctx.session}`);
 
   if (trailers.length === 0) return subject;
   return subject + '\n\n' + trailers.join('\n');
@@ -84,7 +87,10 @@ function buildCommitMessage(ts, opts) {
  * @param {object} [opts.context] - Backup context metadata
  * @param {string} [opts.context.trigger] - 'auto' | 'manual' | 'pre-restore'
  * @param {number} [opts.context.changedFileCount] - Number of changed files
- * @param {string} [opts.context.summary] - Short change summary (e.g. "M src/app.js, A new.ts")
+ * @param {string} [opts.context.summary] - Short change summary (e.g. "Modified 3: a.js, b.js; Added 1: c.js")
+ * @param {string} [opts.context.intent] - Why this snapshot was created (e.g. "refactoring auth middleware")
+ * @param {string} [opts.context.agent] - AI model identifier (e.g. "claude-4-opus")
+ * @param {string} [opts.context.session] - Conversation/session ID
  * @returns {{ status: 'created'|'skipped'|'error', commitHash?: string, shortHash?: string, fileCount?: number, reason?: string, error?: string, secretsExcluded?: string[] }}
  */
 function createGitSnapshot(projectDir, cfg, opts = {}) {

package/references/lib/utils.js

@@ -354,19 +354,31 @@ function timestamp() {
   return new Date().toISOString().replace('T', ' ').substring(0, 19);
 }
 
-function createLogger(logFilePath, maxSizeMB = 10) {
+function createLogger(logFilePath, { maxSizeMB = 1, maxFiles = 3 } = {}) {
   let writeCount = 0;
-  function rotateIfNeeded() {
-    if (++writeCount % 100 !== 0) return;
+  const maxBytes = maxSizeMB * 1024 * 1024;
+
+  function rotate() {
     try {
       const stat = fs.statSync(logFilePath);
-      if (stat.size > maxSizeMB * 1024 * 1024) {
-        const old = logFilePath + '.old';
-        try { fs.unlinkSync(old); } catch { /* ignore */ }
-        fs.renameSync(logFilePath, old);
-      }
-    } catch { /* ignore */ }
+      if (stat.size <= maxBytes) return;
+    } catch { return; }
+    for (let i = maxFiles - 1; i >= 1; i--) {
+      const from = i === 1 ? logFilePath + '.1' : logFilePath + '.' + i;
+      const to = logFilePath + '.' + (i + 1);
+      try { fs.renameSync(from, to); } catch { /* ignore */ }
+    }
+    try { fs.renameSync(logFilePath, logFilePath + '.1'); } catch { /* ignore */ }
+    try { fs.unlinkSync(logFilePath + '.' + (maxFiles + 1)); } catch { /* ignore */ }
   }
+
+  rotate();
+
+  function rotateIfNeeded() {
+    if (++writeCount % 100 !== 0) return;
+    rotate();
+  }
+
   return {
     log(msg, c = 'green') {
       const line = `${timestamp()}  ${msg}`;

package/references/mcp/server.js

@@ -92,8 +92,11 @@ server.tool(
     strategy: z.enum(['git', 'shadow', 'both']).optional().describe('Backup strategy (default: from config, or "git")'),
     message: z.string().optional().describe('Custom commit message for git snapshot'),
     scope: z.enum(['protected', 'all']).optional().describe('Snapshot scope: "protected" = only files matching protect patterns (default when protect is configured); "all" = all files regardless of protect config'),
+    intent: z.string().optional().describe('Why this snapshot is being created — describe the operation about to happen (e.g. "refactoring auth middleware to use JWT")'),
+    agent: z.string().optional().describe('AI model identifier (e.g. "claude-4-opus")'),
+    session: z.string().optional().describe('Conversation or session ID for audit trail'),
   },
-  async ({ path: projectPath, strategy, message, scope }) => {
+  async ({ path: projectPath, strategy, message, scope, intent, agent, session }) => {
     const resolved = path.resolve(projectPath);
     const { loadConfig } = require('../lib/utils');
     const { cfg } = loadConfig(resolved);
@@ -109,10 +112,14 @@ server.tool(
     const results = {};
 
     if (effectiveStrategy === 'git' || effectiveStrategy === 'both') {
+      const context = { trigger: 'manual' };
+      if (intent) context.intent = intent;
+      if (agent) context.agent = agent;
+      if (session) context.session = session;
       results.git = createGitSnapshot(resolved, cfg, {
         branchRef: 'refs/guard/snapshot',
         message: message || `guard: manual snapshot ${new Date().toISOString()}`,
-        context: { trigger: 'manual' },
+        context,
       });
     }