cursor-guard 4.4.1 → 4.5.4

package/references/dashboard/public/style.css

@@ -349,6 +349,19 @@ main {
   max-width: 400px;
   line-height: 1.4;
 }
+.summary-restore-ctx {
+  font-size: 12px;
+  color: var(--amber);
+  background: var(--amber-bg);
+  padding: 4px 10px;
+  border-radius: 4px;
+  border-left: 3px solid var(--amber);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 400px;
+  line-height: 1.4;
+}
 .summary-message {
   font-size: 12px;
   color: var(--text-primary);
@@ -375,6 +388,25 @@ main {
 }
 .summary-detail-line:first-child { padding-top: 2px; }
 
+.summary-collapsed {
+  display: none;
+}
+.summary-expanded .summary-collapsed {
+  display: block;
+}
+.summary-toggle-btn {
+  background: none;
+  border: none;
+  color: var(--blue);
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 2px 0;
+  transition: color var(--transition);
+}
+.summary-toggle-btn:hover { color: var(--text-heading); }
+.summary-expanded .summary-toggle-btn { display: none; }
+
 .summary-pre {
   font-size: 12px;
   line-height: 1.6;
@@ -386,6 +418,30 @@ main {
   border-left: 3px solid var(--blue);
 }
 
+/* ── Summary inline file rows ────────────────────────────── */
+
+.summary-file-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 1px 0;
+  font-size: 11px;
+  line-height: 1.4;
+}
+.summary-file-path {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 220px;
+  font-size: 11px;
+  color: var(--text-primary);
+}
+.summary-file-more {
+  padding: 2px 0;
+  font-style: italic;
+}
+
 /* ── Stats Row ────────────────────────────────────────────── */
 
 .stats-row {
@@ -717,6 +773,58 @@ main {
   line-height: 1.6;
 }
 
+/* ── Drawer: Files Table ──────────────────────────────────── */
+
+.drawer-files-container {
+  margin-top: 6px;
+  max-height: 340px;
+  overflow: auto;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+}
+.drawer-files-loading {
+  padding: 16px;
+  text-align: center;
+}
+.drawer-files-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12px;
+}
+.drawer-files-table th {
+  text-align: left;
+  padding: 8px 12px;
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+  color: var(--text-tertiary);
+  border-bottom: 1px solid var(--border-subtle);
+  background: var(--bg-elevated);
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+.drawer-sort-header { cursor: pointer; transition: color var(--transition); }
+.drawer-sort-header:hover { color: var(--blue); }
+.drawer-files-table td {
+  padding: 5px 12px;
+  border-bottom: 1px solid rgba(71,85,105,.15);
+  vertical-align: middle;
+}
+.drawer-file-path {
+  max-width: 280px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-primary);
+}
+.drawer-file-changes {
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+  color: var(--text-secondary);
+}
+
 /* ── Drawer: Doctor Checks ────────────────────────────────── */
 
 .check-item {
@@ -850,6 +958,236 @@ main {
 }
 .skeleton-table::after { width: 75%; opacity: .6; }
 
+/* ── Alert Card Details ───────────────────────────────────── */
+
+.alert-details {
+  margin-top: 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.alert-detail-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  color: var(--text-secondary);
+}
+.alert-detail-label {
+  font-weight: 600;
+  color: var(--text-tertiary);
+  min-width: 72px;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+}
+.alert-countdown {
+  color: var(--yellow);
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+}
+.alert-numbers {
+  margin-top: 4px;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--yellow);
+  background: var(--yellow-bg);
+  padding: 6px 12px;
+  border-radius: var(--radius-sm);
+  border-left: 3px solid var(--yellow);
+}
+
+.alert-history-toggle-wrap {
+  margin-top: 8px;
+}
+.alert-history-toggle-btn {
+  background: none;
+  border: none;
+  color: var(--text-tertiary);
+  font-size: 11px;
+  cursor: pointer;
+  padding: 2px 0;
+  transition: color var(--transition);
+}
+.alert-history-toggle-btn:hover { color: var(--blue); }
+
+.alert-history {
+  margin-top: 8px;
+  border-top: 1px solid var(--border-subtle);
+  padding-top: 8px;
+}
+.alert-history.alert-history-collapsed { display: none; }
+.alert-history-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+  color: var(--text-tertiary);
+  margin-bottom: 6px;
+}
+.alert-history-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 3px 0;
+  font-size: 11px;
+}
+.badge-expired {
+  background: var(--gray-bg);
+  color: var(--gray);
+  border-color: rgba(100,116,139,.18);
+  font-size: 9px;
+  padding: 1px 6px;
+}
+
+/* ── Alert Files Table ───────────────────────────────────── */
+
+.alert-files-section {
+  margin-top: 10px;
+  border-top: 1px solid var(--border-subtle);
+  padding-top: 8px;
+}
+.alert-files-toggle {
+  background: none;
+  border: none;
+  color: var(--blue);
+  font-size: 11px;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 2px 0;
+  transition: color var(--transition);
+}
+.alert-files-toggle:hover { color: var(--text-heading); }
+
+.alert-files-table-wrap {
+  margin-top: 8px;
+  max-height: 220px;
+  overflow: auto;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+}
+.alert-files-hidden { display: none; }
+
+.alert-files-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 11px;
+}
+.alert-files-table th {
+  text-align: left;
+  padding: 6px 10px;
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .06em;
+  color: var(--text-tertiary);
+  border-bottom: 1px solid var(--border-subtle);
+  background: var(--bg-elevated);
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+.alert-files-table td {
+  padding: 4px 10px;
+  border-bottom: 1px solid rgba(71,85,105,.15);
+  vertical-align: middle;
+}
+.alert-file-path {
+  max-width: 240px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text-primary);
+}
+.alert-file-changes {
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+  color: var(--text-secondary);
+}
+
+.alert-action-badge {
+  display: inline-block;
+  padding: 1px 6px;
+  border-radius: 8px;
+  font-size: 9px;
+  font-weight: 600;
+  letter-spacing: .02em;
+}
+.alert-action-modified { background: var(--blue-bg); color: var(--blue); }
+.alert-action-added    { background: var(--green-bg); color: var(--green); }
+.alert-action-deleted  { background: var(--red-bg); color: var(--red); }
+.alert-action-renamed  { background: var(--purple-bg); color: var(--purple); }
+
+/* ── File Search ─────────────────────────────────────────── */
+
+.file-search-wrap {
+  margin-bottom: 12px;
+}
+.file-search-input {
+  width: 100%;
+  max-width: 360px;
+  background: var(--bg-secondary);
+  color: var(--text-primary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 8px 14px;
+  font-size: 13px;
+  font-family: inherit;
+  transition: border-color var(--transition);
+}
+.file-search-input::placeholder { color: var(--text-tertiary); }
+.file-search-input:focus {
+  outline: none;
+  border-color: var(--blue);
+  box-shadow: 0 0 0 3px var(--blue-bg);
+}
+
+/* ── Filter Count ────────────────────────────────────────── */
+
+.filter-count {
+  font-size: 10px;
+  opacity: .65;
+  font-weight: 400;
+}
+
+/* ── Restore Command Section ─────────────────────────────── */
+
+.restore-cmd-section {
+  margin-top: 18px;
+  padding-top: 16px;
+  border-top: 1px solid var(--border);
+}
+.restore-cmd-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: .08em;
+  color: var(--text-tertiary);
+  margin-bottom: 10px;
+}
+.restore-cmd-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+.restore-cmd-code {
+  flex: 1;
+  font-family: 'JetBrains Mono', 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+  font-size: 11px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-sm);
+  padding: 8px 12px;
+  color: var(--green);
+  word-break: break-all;
+  line-height: 1.5;
+}
+.btn-restore-cmd {
+  flex-shrink: 0;
+  white-space: nowrap;
+}
+
 /* ── Utility ──────────────────────────────────────────────── */
 
 .hidden { display: none !important; }

package/references/dashboard/server.js

@@ -8,7 +8,7 @@ const path = require('path');
 
 const { getDashboard } = require('../lib/core/dashboard');
 const { runDiagnostics } = require('../lib/core/doctor');
-const { listBackups } = require('../lib/core/backups');
+const { listBackups, getBackupFiles } = require('../lib/core/backups');
 
 const PUBLIC_DIR = path.join(__dirname, 'public');
 const DEFAULT_PORT = 3120;
@@ -171,6 +171,13 @@ function handleApi(pathname, query, registry, res) {
     }
   }
 
+  if (pathname === '/api/backup-files') {
+    const hash = query.get('hash');
+    if (!hash) return json(res, { error: 'Missing hash parameter' }, 400);
+    try { return json(res, getBackupFiles(pp, hash)); }
+    catch (e) { return json(res, { error: e.message }, 500); }
+  }
+
   if (pathname === '/api/doctor') {
     try { return json(res, runDiagnostics(pp)); }
     catch (e) { return json(res, { error: e.message }, 500); }

package/references/lib/auto-backup.js

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

package/references/lib/core/anomaly.js

@@ -84,6 +84,27 @@ function checkAnomaly(tracker) {
     return { anomaly: true, alert: lastAlert, suppressed: true };
   }
 
+  // Aggregate per-file details from recent events, deduplicated by path (latest wins)
+  const fileMap = new Map();
+  for (const e of recentEvents) {
+    if (Array.isArray(e.files)) {
+      for (const f of e.files) {
+        if (f && f.path) {
+          const existing = fileMap.get(f.path);
+          if (existing) {
+            existing.added = (existing.added || 0) + (f.added || 0);
+            existing.deleted = (existing.deleted || 0) + (f.deleted || 0);
+          } else {
+            fileMap.set(f.path, { path: f.path, action: f.action || 'modified', added: f.added || 0, deleted: f.deleted || 0 });
+          }
+        }
+      }
+    }
+  }
+  const alertFiles = [...fileMap.values()]
+    .sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted))
+    .slice(0, 50);
+
   const alert = {
     type: 'high_change_velocity',
     detectedAt: now,
@@ -93,6 +114,7 @@ function checkAnomaly(tracker) {
     threshold: tracker.config.filesPerWindow,
     expiresAt: new Date(now + 5 * 60 * 1000).toISOString(),
     recommendation: 'High volume of file changes detected. Consider reviewing recent modifications and creating a manual snapshot.',
+    files: alertFiles.length > 0 ? alertFiles : undefined,
   };
 
   tracker.alerts.push(alert);

package/references/lib/core/backups.js

@@ -48,6 +48,9 @@ const TRAILER_MAP = {
   'Intent':        { key: 'intent' },
   'Agent':         { key: 'agent' },
   'Session':       { key: 'session' },
+  'From':          { key: 'from' },
+  'Restore-To':   { key: 'restoreTo' },
+  'File':          { key: 'restoreFile' },
 };
 
 function parseCommitTrailers(body) {
@@ -395,4 +398,65 @@ function cleanGitRetention(branchRef, gitDirPath, cfg, cwd) {
   return { kept: keepCount, pruned: total - keepCount, mode, rebuilt: true };
 }
 
-module.exports = { listBackups, cleanShadowRetention, cleanGitRetention, parseShadowTimestamp };
+// ── Get backup file details ─────────────────────────────────────
+
+/**
+ * Get structured file-level changes for a specific git backup commit.
+ * Runs diff-tree --numstat + --name-status against parent (or ls-tree for root).
+ *
+ * @param {string} projectDir
+ * @param {string} commitHash - Full or short commit hash
+ * @returns {{ files: Array<{path: string, action: string, added: number, deleted: number}>, error?: string }}
+ */
+function getBackupFiles(projectDir, commitHash) {
+  if (!isGitRepo(projectDir)) {
+    return { files: [], error: 'not a git repository' };
+  }
+
+  const resolved = git(['rev-parse', '--verify', commitHash], { cwd: projectDir, allowFail: true });
+  if (!resolved) {
+    return { files: [], error: `cannot resolve commit: ${commitHash}` };
+  }
+
+  const parentCheck = git(['rev-parse', '--verify', `${resolved}^`], { cwd: projectDir, allowFail: true });
+
+  if (!parentCheck) {
+    const lsOut = git(['ls-tree', '--name-only', '-r', resolved], { cwd: projectDir, allowFail: true });
+    if (!lsOut) return { files: [] };
+    return {
+      files: lsOut.split('\n').filter(Boolean).map(f => ({ path: f, action: 'added', added: 0, deleted: 0 })),
+    };
+  }
+
+  const nameStatusOut = git(['diff-tree', '--no-commit-id', '--name-status', '-r', `${resolved}^`, resolved], { cwd: projectDir, allowFail: true });
+  const numstatOut = git(['diff-tree', '--no-commit-id', '--numstat', '-r', `${resolved}^`, resolved], { cwd: projectDir, 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');
+      stats[fname] = { added: add === '-' ? 0 : parseInt(add, 10), deleted: del === '-' ? 0 : parseInt(del, 10) };
+    }
+  }
+
+  const ACTION_MAP = { M: 'modified', A: 'added', D: 'deleted' };
+  const files = [];
+  if (nameStatusOut) {
+    for (const line of nameStatusOut.split('\n').filter(Boolean)) {
+      const tab = line.indexOf('\t');
+      if (tab < 0) continue;
+      const code = line.substring(0, tab).trim();
+      const filePart = line.substring(tab + 1);
+      const action = code.startsWith('R') ? 'renamed' : (ACTION_MAP[code] || 'modified');
+      const fileName = filePart.split('\t').pop();
+      const s = stats[fileName] || { added: 0, deleted: 0 };
+      files.push({ path: fileName, action, added: s.added, deleted: s.deleted });
+    }
+  }
+
+  files.sort((a, b) => (b.added + b.deleted) - (a.added + a.deleted));
+  return { files };
+}
+
+module.exports = { listBackups, getBackupFiles, cleanShadowRetention, cleanGitRetention, parseShadowTimestamp };

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

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

package/references/lib/core/doctor.js

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