@misterhuydo/cairn-mcp 1.7.5 → 1.9.0

package/README.md

@@ -44,7 +44,7 @@ No need to re-run `cairn install` — hooks and MCP config carry over between ve
 
 | Hook | Trigger | Effect |
 |---|---|---|
-| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline to save tokens |
+| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline with **line numbers** to save tokens |
 | `PreToolUse[Edit]` | Every file edit | Blocks Edit if Claude only saw compressed content — requires a full re-read first |
 | `Stop` | End of every response | Session auto-saved to `.cairn/session.json` |
 | `UserPromptSubmit` | First message of a new session | Fresh project: Claude prompted to run `cairn_maintain`. Returning session: Claude prompted to run `cairn_resume` |
@@ -66,11 +66,11 @@ No manual steps. The index lives in `.cairn/index.db` inside your project — li
 
 | Tool | What it does |
 |---|---|
-| `cairn_maintain` | Full index of the current project |
+| `cairn_maintain` | Full index of the current project. Suggests adding `.cairn/` to `.gitignore` if not already present |
 | `cairn_resume` | Restore last session + re-index only changed files |
-| `cairn_search` | Find classes, functions, components by name or concept |
+| `cairn_search` | Find classes, functions, components by name or concept — results include file path and **line number** |
 | `cairn_describe` | Summarize what a folder or module does |
-| `cairn_outline` | Structural outline + heuristic issue detection. On large federated projects returns a per-service summary; use `repo` param to drill into one service |
+| `cairn_outline` | Structural outline with **line numbers** per symbol + heuristic issue detection. On large federated projects returns a per-service summary; use `repo` param to drill into one service |
 | `cairn_code_graph` | Dependency health — instability, cycles, load-bearing modules |
 | `cairn_security` | Scan for XSS, SQLi, hardcoded secrets, weak crypto, and more |
 | `cairn_todos` | Scan codebase for TODO/FIXME/HACK comments, add manual items, resolve and list them |

package/bin/cairn-cli.js

@@ -14,91 +14,148 @@ const MINIFY_LANGS = new Set(['java', 'typescript', 'javascript', 'vue', 'python
 
 // Memory sync scripts deployed to ~/.claude/scripts/ during global install.
 // Using forward slashes in hook commands — bash on Windows handles them fine.
-const SYNC_FORWARD_SCRIPT = `\
-"""
-Forward sync: Claude Code auto-memory -> .cairn/memory/auto-memory/
-Triggered as a PostToolUse hook on Write.
-Only fires when the written file is inside Claude's projects memory dir
-and the current project has a .cairn/ folder.
-"""
-import sys, json, os, shutil
-
-data = json.load(sys.stdin)
-fp = data.get('tool_input', {}).get('file_path', '')
-
-user_home = os.path.expanduser('~')
-claude_projects = os.path.normpath(os.path.join(user_home, '.claude', 'projects'))
-
-fp_norm = os.path.normpath(fp)
-if not fp_norm.startswith(claude_projects) or 'memory' not in fp_norm:
-    sys.exit(0)
-
-cwd = os.getcwd()
-if not os.path.exists(os.path.join(cwd, '.cairn')):
-    sys.exit(0)
-
-memory_dir = os.path.dirname(fp_norm)
-dest = os.path.join(cwd, '.cairn', 'memory', 'auto-memory')
-os.makedirs(dest, exist_ok=True)
-
-for f in os.listdir(memory_dir):
-    src = os.path.join(memory_dir, f)
-    if os.path.isfile(src):
-        shutil.copy2(src, dest)
+const SYNC_FORWARD_SCRIPT = `#!/usr/bin/env node
+// Forward sync: Claude Code auto-memory -> .cairn/memory/auto-memory/
+// Triggered as a PostToolUse hook on Write.
+// Only fires when the written file is inside Claude's projects memory dir
+// and the current project has a .cairn/ folder.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+let stdinData = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', c => { stdinData += c; });
+process.stdin.on('end', () => {
+  let fp;
+  try { fp = JSON.parse(stdinData)?.tool_input?.file_path || ''; } catch { process.exit(0); }
+  if (!fp) process.exit(0);
+
+  const claudeProjects = path.normalize(path.join(os.homedir(), '.claude', 'projects'));
+  const fpNorm = path.normalize(fp);
+  if (!fpNorm.startsWith(claudeProjects) || !fpNorm.includes('memory')) process.exit(0);
+
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, '.cairn'))) process.exit(0);
+
+  const memoryDir = path.dirname(fpNorm);
+  const cairnMemory = path.join(cwd, '.cairn', 'memory');
+  const dest = path.join(cairnMemory, 'auto-memory');
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const f of fs.readdirSync(memoryDir)) {
+    // Skip files that exist in canonical top-level — those are mirrored from cairn_memo,
+    // not out-of-band auto-memory writes, so backing them up would duplicate canonical content.
+    if (fs.existsSync(path.join(cairnMemory, f))) continue;
+    const src = path.join(memoryDir, f);
+    let st;
+    try { st = fs.statSync(src); } catch { continue; }
+    if (!st.isFile()) continue;
+    const dst = path.join(dest, f);
+    fs.copyFileSync(src, dst);
+    try { fs.utimesSync(dst, st.atime, st.mtime); } catch {}
+  }
+});
 `;
 
-const SYNC_RESTORE_SCRIPT = `\
-"""
-Restore sync: .cairn/memory/ -> Claude Code memory dir for current location.
-Triggered as a UserPromptSubmit hook on each new session prompt.
-Two passes:
-  1. New-machine restore: copy .cairn/memory/auto-memory/ -> Claude memory dir
-     (only when target is empty/missing, preserves Claude-native memory on new drive)
-  2. Always: sync .cairn/memory/ (top-level files only) -> Claude memory dir
-     using mtime comparison so cairn_memo writes are always reflected.
-Path encoding: H:\\\\Projects\\\\Cairn -> H--Projects-Cairn
-  (both ':' and '\\\\' map to '-', so ':' + '\\\\' = '--')
-"""
-import sys, os, shutil
-
-cwd = os.getcwd()
-cairn_memory = os.path.join(cwd, '.cairn', 'memory')
-
-if not os.path.exists(cairn_memory):
-    sys.exit(0)
-
-encoded = cwd.replace(':', '-').replace('\\\\', '-').replace('/', '-').lstrip('-')
-user_home = os.path.expanduser('~')
-memory_dir = os.path.join(user_home, '.claude', 'projects', encoded, 'memory')
-os.makedirs(memory_dir, exist_ok=True)
-
-# Pass 1: new-machine restore from auto-memory backup
-cairn_auto_memory = os.path.join(cairn_memory, 'auto-memory')
-if os.path.exists(cairn_auto_memory):
-    target_empty = not any(f.endswith('.md') for f in os.listdir(memory_dir))
-    if target_empty:
-        restored = 0
-        for f in os.listdir(cairn_auto_memory):
-            src = os.path.join(cairn_auto_memory, f)
-            if os.path.isfile(src):
-                shutil.copy2(src, memory_dir)
-                restored += 1
-        if restored > 0:
-            print(f"[cairn] Restored {restored} memory files from .cairn/memory/auto-memory/ (new project location detected)")
-
-# Pass 2: always sync top-level .cairn/memory/ files (cairn_memo writes) -> Claude memory dir
-synced = 0
-for f in os.listdir(cairn_memory):
-    src = os.path.join(cairn_memory, f)
-    if not os.path.isfile(src):
-        continue  # skip subdirs like auto-memory/
-    dst = os.path.join(memory_dir, f)
-    if not os.path.exists(dst) or os.path.getmtime(src) > os.path.getmtime(dst):
-        shutil.copy2(src, dst)
-        synced += 1
-
-if synced > 0:
-    print(f"[cairn] Synced {synced} memory file(s) from .cairn/memory/ to Claude memory dir")
+const SYNC_RESTORE_SCRIPT = `#!/usr/bin/env node
+// Restore sync: .cairn/memory/ -> Claude Code memory dir for current location.
+// Triggered as a UserPromptSubmit hook on each new session prompt.
+// Three passes:
+//   0. Bootstrap: capture any auto-memory files newer/missing in .cairn/memory/auto-memory/
+//      (catches files pre-dating the forward-sync hook install).
+//   1. New-machine restore: copy .cairn/memory/auto-memory/ -> Claude memory dir
+//      (only when target is empty, preserves Claude-native memory on new drive)
+//   2. Always: mtime-mirror .cairn/memory/*.md -> Claude memory dir
+//      (so cairn_memo writes are reflected)
+// Path encoding: H:\\Projects\\Cairn -> H--Projects-Cairn
+//   (':', '\\', '/' all map to '-')
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const cwd = process.cwd();
+const cairnMemory = path.join(cwd, '.cairn', 'memory');
+if (!fs.existsSync(cairnMemory)) process.exit(0);
+
+const encoded = cwd.replace(/[:/\\\\]/g, '-').replace(/^-+/, '');
+const memoryDir = path.join(os.homedir(), '.claude', 'projects', encoded, 'memory');
+fs.mkdirSync(memoryDir, { recursive: true });
+
+const cairnAutoMemory = path.join(cairnMemory, 'auto-memory');
+
+function copyWithMtime(src, dst, srcStat) {
+  fs.copyFileSync(src, dst);
+  try { fs.utimesSync(dst, srcStat.atime, srcStat.mtime); } catch {}
+}
+
+// Pass 0: bootstrap — capture auto-memory files missing/newer in .cairn/memory/auto-memory/
+// (catches files that pre-date the forward-sync hook install)
+// Skip files present in canonical top-level: they are mirrored from cairn_memo, not auto-memory.
+const claudeFiles = fs.readdirSync(memoryDir);
+let bootstrapped = 0;
+if (claudeFiles.length > 0) {
+  fs.mkdirSync(cairnAutoMemory, { recursive: true });
+  for (const f of claudeFiles) {
+    if (fs.existsSync(path.join(cairnMemory, f))) continue;
+    const src = path.join(memoryDir, f);
+    let srcStat;
+    try { srcStat = fs.statSync(src); } catch { continue; }
+    if (!srcStat.isFile()) continue;
+    const dst = path.join(cairnAutoMemory, f);
+    let needCopy = !fs.existsSync(dst);
+    if (!needCopy) {
+      try { needCopy = srcStat.mtimeMs > fs.statSync(dst).mtimeMs; } catch { needCopy = true; }
+    }
+    if (needCopy) {
+      copyWithMtime(src, dst, srcStat);
+      bootstrapped++;
+    }
+  }
+}
+if (bootstrapped > 0) {
+  process.stdout.write(\`[cairn] Bootstrapped \${bootstrapped} auto-memory file(s) into .cairn/memory/auto-memory/\\n\`);
+}
+
+// Pass 1: new-machine restore from auto-memory backup (only when target empty)
+if (fs.existsSync(cairnAutoMemory)) {
+  const targetEmpty = !fs.readdirSync(memoryDir).some(f => f.endsWith('.md'));
+  if (targetEmpty) {
+    let restored = 0;
+    for (const f of fs.readdirSync(cairnAutoMemory)) {
+      const src = path.join(cairnAutoMemory, f);
+      let srcStat;
+      try { srcStat = fs.statSync(src); } catch { continue; }
+      if (!srcStat.isFile()) continue;
+      copyWithMtime(src, path.join(memoryDir, f), srcStat);
+      restored++;
+    }
+    if (restored > 0) {
+      process.stdout.write(\`[cairn] Restored \${restored} memory files from .cairn/memory/auto-memory/ (new project location detected)\\n\`);
+    }
+  }
+}
+
+// Pass 2: mtime-mirror top-level .cairn/memory/*.md -> Claude memory dir
+let synced = 0;
+for (const f of fs.readdirSync(cairnMemory)) {
+  const src = path.join(cairnMemory, f);
+  let srcStat;
+  try { srcStat = fs.statSync(src); } catch { continue; }
+  if (!srcStat.isFile()) continue;  // skip subdirs like auto-memory/
+  const dst = path.join(memoryDir, f);
+  let needCopy = !fs.existsSync(dst);
+  if (!needCopy) {
+    try { needCopy = srcStat.mtimeMs > fs.statSync(dst).mtimeMs; } catch { needCopy = true; }
+  }
+  if (needCopy) {
+    copyWithMtime(src, dst, srcStat);
+    synced++;
+  }
+}
+if (synced > 0) {
+  process.stdout.write(\`[cairn] Synced \${synced} memory file(s) from .cairn/memory/ to Claude memory dir\\n\`);
+}
 `;
 
 process.on('uncaughtException', (e) => {
@@ -479,6 +536,82 @@ if (subcommand === '--version' || subcommand === '-v') {
   fs.writeFileSync(lockPath, new Date().toISOString(), 'utf8');
   process.exit(0);
 
+} else if (subcommand === 'roadmap-hint') {
+  // Stop hook: print the roadmap tree + cursor only when a cursor is set.
+  // Silent (exit 0) for projects with no .cairn, no DB, or no cursor — so
+  // normal chat is unaffected. Activates the moment cairn_todos focus is called.
+  const cairnDir = path.join(process.cwd(), '.cairn');
+  const dbPath = path.join(cairnDir, 'index.db');
+  if (!fs.existsSync(dbPath)) process.exit(0);
+
+  let DatabaseSync;
+  try { ({ DatabaseSync } = await import('node:sqlite')); } catch { process.exit(0); }
+
+  let db;
+  try { db = new DatabaseSync(dbPath, { readonly: true }); } catch { process.exit(0); }
+
+  try {
+    const cursorRow = db.prepare(
+      "SELECT todo_id FROM roadmap_cursor WHERE singleton = 1"
+    ).get();
+    const cursorId = cursorRow?.todo_id ?? null;
+    if (cursorId == null) { db.close(); process.exit(0); }
+
+    const all = db.prepare(
+      'SELECT id, parent_id, position, status, text FROM todos ORDER BY IFNULL(parent_id, -1), position, id'
+    ).all();
+    db.close();
+
+    const STATUS_BOX = { open: '[ ]', in_progress: '[~]', done: '[x]', blocked: '[!]' };
+    const childrenByParent = new Map();
+    for (const t of all) {
+      const key = t.parent_id ?? null;
+      if (!childrenByParent.has(key)) childrenByParent.set(key, []);
+      childrenByParent.get(key).push(t);
+    }
+
+    const lines = [];
+    const visit = (parentId, depth) => {
+      for (const t of childrenByParent.get(parentId) || []) {
+        const arrow = cursorId === t.id ? ' →' : '';
+        lines.push(`${'  '.repeat(depth)}${STATUS_BOX[t.status] || '[?]'}${arrow} ${t.text} (id:${t.id})`);
+        visit(t.id, depth + 1);
+      }
+    };
+    visit(null, 0);
+
+    // Compute "Next" via DFS: first open child of cursor → next open sibling/uncle.
+    const isOpenish = (s) => s === 'open' || s === 'in_progress';
+    const findNext = (fromId) => {
+      const kids = (childrenByParent.get(fromId) || []).filter(t => isOpenish(t.status));
+      if (kids.length > 0) return kids[0];
+      let curId = fromId;
+      while (curId != null) {
+        const cur = all.find(t => t.id === curId);
+        if (!cur) return null;
+        const siblings = (childrenByParent.get(cur.parent_id ?? null) || [])
+          .filter(t => isOpenish(t.status) && (t.position > cur.position || (t.position === cur.position && t.id > cur.id)));
+        if (siblings.length > 0) return siblings[0];
+        curId = cur.parent_id;
+      }
+      return null;
+    };
+    const cursorNode = all.find(t => t.id === cursorId);
+    const next = findNext(cursorId);
+
+    const out = [
+      '[cairn] ROADMAP — cursor is active. Tree:',
+      ...lines.map(l => '[cairn]   ' + l),
+      cursorNode ? `[cairn] Current: (id:${cursorNode.id}) ${cursorNode.text}` : '',
+      next ? `[cairn] Next:    (id:${next.id}) ${next.text}` : '[cairn] Next:    (no open todos remaining)',
+      '[cairn] Use cairn_todos resolve <id> to mark done (auto-advances), focus <id> to move cursor, or next to advance manually.',
+    ].filter(Boolean);
+    process.stdout.write(out.join('\n') + '\n');
+  } catch {
+    try { db?.close(); } catch {}
+  }
+  process.exit(0);
+
 } else if (subcommand === 'install') {
   // One-shot setup: register MCP server in ~/.claude.json + install global hooks.
   const platform = process.platform;
@@ -509,10 +642,11 @@ if (subcommand === '--version' || subcommand === '-v') {
   console.log('  PreToolUse[Read]     -> cairn minify                   (compress source files for reading)');
   console.log('  PreToolUse[Edit]     -> cairn edit-guard               (block Edit until re-read with full content)')
   console.log('  PreToolUse[Write]    -> cairn edit-guard               (clear minify state before full file overwrite)');
-  console.log('  PostToolUse[Write]   -> sync-memory-forward.py         (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
+  console.log('  PostToolUse[Write]   -> sync-memory-forward.mjs        (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
   console.log('  Stop                 -> cairn checkpoint --auto         (auto-save session)');
+  console.log('  Stop                 -> cairn roadmap-hint              (re-print roadmap when cursor is active)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
-  console.log('  UserPromptSubmit     -> sync-memory-restore.py          (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
+  console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
   console.log('');
   console.log('Restart Claude Code to activate the MCP server, then open any project and start working.');
   console.log('Upgrade any time with: npm install -g @misterhuydo/cairn-mcp');
@@ -532,17 +666,18 @@ if (subcommand === '--version' || subcommand === '-v') {
   console.log('  PreToolUse[Edit]     -> cairn edit-guard               (block Edit until re-read with full content)')
   console.log('  PreToolUse[Write]    -> cairn edit-guard               (clear minify state before full file overwrite)');
   if (isGlobal) {
-    console.log('  PostToolUse[Write]   -> sync-memory-forward.py         (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
+    console.log('  PostToolUse[Write]   -> sync-memory-forward.mjs        (sync ~/.claude/memory -> .cairn/memory/auto-memory/)');
   }
   console.log('  Stop                 -> cairn checkpoint --auto         (auto-save session)');
+  console.log('  Stop                 -> cairn roadmap-hint              (re-print roadmap when cursor is active)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
   if (isGlobal) {
-    console.log('  UserPromptSubmit     -> sync-memory-restore.py          (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
+    console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
   }
   process.exit(0);
 
 } else {
-  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | resume-hint>');
+  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | resume-hint | roadmap-hint>');
   process.exit(1);
 }
 
@@ -575,36 +710,58 @@ function applyHooks(settingsDir, isGlobal) {
   const stopHooks = settings.hooks.Stop || [];
   if (!stopHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn checkpoint --auto'))) {
     stopHooks.push({ hooks: [{ type: 'command', command: 'cairn checkpoint --auto' }] });
-    settings.hooks.Stop = stopHooks;
   }
+  // Stop: cairn roadmap-hint (silent unless a roadmap_cursor is set)
+  if (!stopHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn roadmap-hint'))) {
+    stopHooks.push({ hooks: [{ type: 'command', command: 'cairn roadmap-hint' }] });
+  }
+  settings.hooks.Stop = stopHooks;
 
   // UserPromptSubmit: cairn resume-hint
-  const submitHooks = settings.hooks.UserPromptSubmit || [];
+  let submitHooks = settings.hooks.UserPromptSubmit || [];
   if (!submitHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn resume-hint'))) {
     submitHooks.push({ hooks: [{ type: 'command', command: 'cairn resume-hint' }] });
   }
 
   if (isGlobal) {
-    // Deploy memory sync scripts to ~/.claude/scripts/
+    // Deploy memory sync scripts to ~/.claude/scripts/ (Node — cross-platform, no python3 required)
     const scriptsDir = path.join(settingsDir, 'scripts');
     fs.mkdirSync(scriptsDir, { recursive: true });
-    const forwardScript = path.join(scriptsDir, 'sync-memory-forward.py');
-    const restoreScript = path.join(scriptsDir, 'sync-memory-restore.py');
+    const forwardScript = path.join(scriptsDir, 'sync-memory-forward.mjs');
+    const restoreScript = path.join(scriptsDir, 'sync-memory-restore.mjs');
     fs.writeFileSync(forwardScript, SYNC_FORWARD_SCRIPT, 'utf8');
     fs.writeFileSync(restoreScript, SYNC_RESTORE_SCRIPT, 'utf8');
 
+    // Clean up legacy Python scripts from prior installs
+    for (const legacy of ['sync-memory-forward.py', 'sync-memory-restore.py']) {
+      const p = path.join(scriptsDir, legacy);
+      if (fs.existsSync(p)) { try { fs.unlinkSync(p); } catch {} }
+    }
+
     // Use forward slashes in hook commands — works across bash on Windows and Unix
-    const fwdCmd = `python3 "${scriptsDir.replace(/\\/g, '/')}/sync-memory-forward.py"`;
-    const rstCmd = `python3 "${scriptsDir.replace(/\\/g, '/')}/sync-memory-restore.py"`;
+    const scriptsDirFwd = scriptsDir.replace(/\\/g, '/');
+    const fwdCmd = `node "${scriptsDirFwd}/sync-memory-forward.mjs"`;
+    const rstCmd = `node "${scriptsDirFwd}/sync-memory-restore.mjs"`;
+
+    // Strip stale python3 .py references from prior installs (avoids duplicate hooks firing)
+    const isLegacyPyCmd = (cmd) => typeof cmd === 'string' &&
+      /python3?\s+.*sync-memory-(forward|restore)\.py/.test(cmd);
+    const stripLegacy = (entries) => entries
+      .map(entry => ({
+        ...entry,
+        hooks: (entry.hooks || []).filter(h => !isLegacyPyCmd(h.command)),
+      }))
+      .filter(entry => entry.hooks.length > 0);
 
     // PostToolUse[Write]: forward sync Claude memory -> .cairn/memory/auto-memory/
-    const postHooks = settings.hooks.PostToolUse || [];
+    let postHooks = stripLegacy(settings.hooks.PostToolUse || []);
     if (!postHooks.some(h => h.matcher === 'Write' && h.hooks?.some(hh => hh.command === fwdCmd))) {
       postHooks.push({ matcher: 'Write', hooks: [{ type: 'command', command: fwdCmd }] });
     }
     settings.hooks.PostToolUse = postHooks;
 
     // UserPromptSubmit: sync .cairn/memory/ -> Claude memory dir (always, mtime-based)
+    submitHooks = stripLegacy(submitHooks);
     if (!submitHooks.some(h => h.hooks?.some(hh => hh.command === rstCmd))) {
       submitHooks.push({ hooks: [{ type: 'command', command: rstCmd }] });
     }

package/index.js

@@ -262,20 +262,23 @@ Use to: get a project-wide bird's-eye view, triage code quality, find where to l
     },
     {
       name: 'cairn_todos',
-      description: 'Manage TODO/FIXME/HACK/XXX items. Scans the codebase for TODO-style comments and lets you add your own. Stats are included in cairn_maintain and cairn_resume reports.',
+      description: 'Manage TODO/FIXME/HACK/XXX items and multi-phase roadmaps. Supports a tree of nested phases with a "current cursor" pointer so multi-phase plans survive context drift. Use action=tree to render the roadmap, focus to set the cursor, next to advance. Stats are included in cairn_maintain and cairn_resume reports.',
       inputSchema: {
         type: 'object',
         properties: {
           action: {
             type: 'string',
-            enum: ['list', 'add', 'resolve', 'scan'],
-            description: 'list: show todos | add: create a manual todo | resolve: mark done by id | scan: re-scan codebase',
+            enum: ['list', 'tree', 'add', 'resolve', 'focus', 'next', 'set_status', 'scan'],
+            description: 'list: flat list | tree: hierarchical roadmap with cursor | add: create manual todo (use parent + position for nesting) | resolve: mark done | focus: move cursor to id, mark in_progress, propagate up | next: DFS-advance cursor to next open node | set_status: set status to open|in_progress|done|blocked | scan: re-scan codebase',
           },
-          text:   { type: 'string',  description: 'Text for the new todo (add action)' },
-          kind:   { type: 'string',  enum: ['TODO', 'FIXME', 'HACK', 'XXX', 'NOTE'], description: 'Kind for new todo (default: TODO)' },
-          id:     { type: 'number',  description: 'Todo ID to resolve (resolve action)' },
-          status: { type: 'string',  enum: ['open', 'done'], description: 'Filter by status (list action)' },
-          source: { type: 'string',  enum: ['scan', 'manual'], description: 'Filter by source (list action)' },
+          text:     { type: 'string',  description: 'Text for the new todo (add action)' },
+          kind:     { type: 'string',  enum: ['TODO', 'FIXME', 'HACK', 'XXX', 'NOTE'], description: 'Kind for new todo (default: TODO)' },
+          id:       { type: 'number',  description: 'Todo ID (resolve, focus, set_status)' },
+          status:   { type: 'string',  enum: ['open', 'in_progress', 'done', 'blocked'], description: 'Filter (list) or new value (set_status)' },
+          source:   { type: 'string',  enum: ['scan', 'manual'], description: 'Filter by source (list action)' },
+          parent:   { type: 'number',  description: 'Parent todo ID for nesting (add action). Omit for root/phase.' },
+          position: { type: 'number',  description: 'Sibling order within parent (add action). Auto-appends if omitted.' },
+          compact:  { type: 'boolean', description: 'Compact tree render — strips id/kind tags (tree action)' },
         },
         required: ['action'],
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.7.5",
+  "version": "1.9.0",
   "description": "MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.",
   "type": "module",
   "main": "index.js",

package/src/graph/db.js

@@ -67,9 +67,16 @@ const SCHEMA = `
     kind        TEXT NOT NULL DEFAULT 'TODO',
     text        TEXT NOT NULL,
     status      TEXT NOT NULL DEFAULT 'open',
+    parent_id   INTEGER REFERENCES todos(id) ON DELETE SET NULL,
+    position    INTEGER NOT NULL DEFAULT 0,
     created_at  TEXT NOT NULL DEFAULT (datetime('now')),
     resolved_at TEXT
   );
+
+  CREATE TABLE IF NOT EXISTS roadmap_cursor (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    todo_id   INTEGER REFERENCES todos(id) ON DELETE SET NULL
+  );
 `;
 
 // Each sub-DB gets its IDs offset by this multiplier to prevent collisions
@@ -190,6 +197,24 @@ export function openDB() {
   db.exec(SCHEMA);
   // Migration: add line column to existing DBs that predate v1.7.0
   try { db.exec('ALTER TABLE main.symbols ADD COLUMN line INTEGER'); } catch {}
+  // Migration: roadmap tree columns on todos (idempotent — fails silently if present)
+  let addedRoadmapCols = false;
+  try { db.exec('ALTER TABLE main.todos ADD COLUMN parent_id INTEGER REFERENCES todos(id) ON DELETE SET NULL'); addedRoadmapCols = true; } catch {}
+  try { db.exec('ALTER TABLE main.todos ADD COLUMN position INTEGER NOT NULL DEFAULT 0'); addedRoadmapCols = true; } catch {}
+  if (addedRoadmapCols) {
+    // Backfill position by id order within each parent group (null parent = root).
+    // ROW_NUMBER() requires SQLite 3.25+, which node:sqlite ships.
+    db.exec(`
+      UPDATE main.todos AS t
+      SET position = (
+        SELECT rn - 1 FROM (
+          SELECT id, ROW_NUMBER() OVER (
+            PARTITION BY IFNULL(parent_id, -1) ORDER BY id
+          ) AS rn FROM main.todos
+        ) ord WHERE ord.id = t.id
+      )
+    `);
+  }
   mountParentSubIndexes(db);
   refreshFederatedViews(db);
   return db;

package/src/tools/checkpoint.js

@@ -47,14 +47,19 @@ export function checkpoint(_db, { message, active_files = [], notes = [] }) {
   const sessionPath = path.join(cairnDir, 'session.json');
   const dateStr = new Date().toISOString().slice(0, 10);
 
-  // Snapshot mtimes of active files
+  // Snapshot mtimes of all indexed files so resume can detect changes accurately.
+  // Without a full snapshot, resume labels every non-active file as "new" and
+  // triggers a full reindex on every call.
   const mtimeSnapshot = {};
-  for (const filePath of active_files) {
-    try {
-      mtimeSnapshot[filePath] = fs.statSync(filePath).mtimeMs;
-    } catch {
-      // File may not exist yet
+  try {
+    const rows = _db.prepare('SELECT path FROM main.files').all();
+    for (const { path: filePath } of rows) {
+      try { mtimeSnapshot[filePath] = fs.statSync(filePath).mtimeMs; } catch { }
     }
+  } catch { /* DB may not exist on first run */ }
+  // Also include active_files in case they are not yet indexed
+  for (const filePath of active_files) {
+    try { mtimeSnapshot[filePath] = fs.statSync(filePath).mtimeMs; } catch { }
   }
 
   // Process all notes: long strings get filed, short ones stay inline, refs pass through

package/src/tools/resume.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import path from 'path';
-import { execSync } from 'child_process';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
 import { getCairnDir, getProjectRoot, getMemoryDir } from '../graph/cwd.js';
 import { walkRepo } from '../indexer/fileWalker.js';
 import { getAttachedSchemas } from '../graph/db.js';
@@ -125,11 +127,47 @@ export async function resume(db) {
   // Count open todos for status report
   let openTodos = 0;
   try {
-    openTodos = db.prepare('SELECT COUNT(*) AS n FROM main.todos WHERE status = \'open\'').get().n;
+    openTodos = db.prepare("SELECT COUNT(*) AS n FROM main.todos WHERE status IN ('open', 'in_progress')").get().n;
   } catch {
     // todos table not yet present in older indexes; ignore
   }
 
+  // Roadmap surfacing: render compact tree if a cursor is set or any todo is nested.
+  let roadmap = null;
+  try {
+    const cursorRow = db.prepare('SELECT todo_id FROM main.roadmap_cursor WHERE singleton = 1').get();
+    const cursorId = cursorRow?.todo_id ?? null;
+    const hasNested = db.prepare('SELECT 1 FROM main.todos WHERE parent_id IS NOT NULL LIMIT 1').get();
+    if (cursorId != null || hasNested) {
+      const all = db.prepare(
+        'SELECT id, parent_id, position, status, text FROM main.todos ORDER BY IFNULL(parent_id, -1), position, id'
+      ).all();
+      const STATUS_BOX = { open: '[ ]', in_progress: '[~]', done: '[x]', blocked: '[!]' };
+      const childrenByParent = new Map();
+      for (const t of all) {
+        const key = t.parent_id ?? null;
+        if (!childrenByParent.has(key)) childrenByParent.set(key, []);
+        childrenByParent.get(key).push(t);
+      }
+      const lines = [];
+      const visit = (parentId, depth) => {
+        for (const t of childrenByParent.get(parentId) || []) {
+          const arrow = cursorId === t.id ? ' →' : '';
+          lines.push(`${'  '.repeat(depth)}${STATUS_BOX[t.status] || '[?]'}${arrow} ${t.text} (id:${t.id})`);
+          visit(t.id, depth + 1);
+        }
+      };
+      visit(null, 0);
+      const cursorFull = cursorId ? db.prepare('SELECT id, text FROM main.todos WHERE id = ?').get(cursorId) : null;
+      roadmap = {
+        tree: lines.join('\n'),
+        cursor: cursorFull ? { id: cursorFull.id, text: cursorFull.text } : null,
+      };
+    }
+  } catch {
+    // roadmap_cursor table missing on very old indexes; ignore
+  }
+
   // Build human-readable resume summary
   const changedSummary = changed.length > 0
     ? changed.slice(0, 10).map(c => `${c.change}: ${path.relative(getProjectRoot(), c.file).replace(/\\/g, '/')}`).join(', ')
@@ -141,6 +179,7 @@ export async function resume(db) {
     changed.length > 0 ? `Files changed since checkpoint: ${changedSummary}` : 'No files changed since checkpoint.',
     subSchemas.length > 0 ? `Federated sub-indexes: ${subSchemas.length}` : '',
     openTodos > 0 ? `Open todos: ${openTodos}` : '',
+    roadmap?.cursor ? `Roadmap cursor → (id:${roadmap.cursor.id}) ${roadmap.cursor.text}` : '',
     session.notes?.length > 0 ? `Notes: ${session.notes.map(n => (n && typeof n === 'object' && n.ref) ? `${n.description} (see: ${n.ref})` : String(n)).join(' | ')}` : '',
   ].filter(Boolean).join(' ');
 
@@ -168,32 +207,31 @@ export async function resume(db) {
     resume_summary: resumeSummary,
   };
   if (gitignoreHint) result.gitignore_hint = gitignoreHint;
+  if (roadmap) result.roadmap = roadmap;
   if (gitSnapshotNotes.length > 0) {
     result.migrated = `Removed ${gitSnapshotNotes.length} legacy git-snapshot note(s). Original session backed up to session.bak.json.`;
   }
 
-  // Git state — lets Claude determine what's resolved vs still in-flight,
-  // regardless of checkpoint staleness.
+  // Git state — run all three queries in parallel to avoid sequential git startup overhead.
   const gitRoot = getProjectRoot();
-  try {
-    const since = new Date(session.checkpoint_at).toISOString();
-    const raw = execSync(`git log --oneline --after="${since}"`, {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000,
-    }).trim();
+  const since = new Date(session.checkpoint_at).toISOString();
+  const [logResult, diffResult, statusResult] = await Promise.allSettled([
+    execAsync(`git log --oneline --after="${since}"`, { cwd: gitRoot, timeout: 5000 }),
+    execAsync('git diff --name-only HEAD', { cwd: gitRoot, timeout: 5000 }),
+    execAsync('git status --short', { cwd: gitRoot, timeout: 5000 }),
+  ]);
+  if (logResult.status === 'fulfilled') {
+    const raw = logResult.value.stdout.trim();
     if (raw) result.commits_since_checkpoint = raw.split('\n');
-  } catch { }
-  try {
-    const raw = execSync('git diff --name-only HEAD', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000,
-    }).trim();
+  }
+  if (diffResult.status === 'fulfilled') {
+    const raw = diffResult.value.stdout.trim();
     if (raw) result.uncommitted_changes = raw.split('\n');
-  } catch { }
-  try {
-    const raw = execSync('git status --short', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000,
-    }).trim();
+  }
+  if (statusResult.status === 'fulfilled') {
+    const raw = statusResult.value.stdout.trim();
     if (raw) result.git_status = raw;
-  } catch { }
+  }
 
   if (relocation) result.relocated = relocation;
   if (preferences.length > 0) {

package/src/tools/todos.js

@@ -1,8 +1,113 @@
 import { walkRepo } from '../indexer/fileWalker.js';
 import { scanTodos } from '../indexer/todoScanner.js';
 
+const STATUS_BOX = {
+  open: '[ ]',
+  in_progress: '[~]',
+  done: '[x]',
+  blocked: '[!]',
+};
+
+const VALID_STATUS = new Set(['open', 'in_progress', 'done', 'blocked']);
+
+function getCursor(db) {
+  const row = db.prepare('SELECT todo_id FROM main.roadmap_cursor WHERE singleton = 1').get();
+  return row?.todo_id ?? null;
+}
+
+function setCursor(db, todoId) {
+  db.prepare('INSERT OR REPLACE INTO main.roadmap_cursor (singleton, todo_id) VALUES (1, ?)').run(todoId);
+}
+
+function clearCursor(db) {
+  db.prepare('DELETE FROM main.roadmap_cursor WHERE singleton = 1').run();
+}
+
+// Mark ancestors as in_progress (only if currently 'open' — don't downgrade done/blocked).
+function propagateInProgressUp(db, todoId) {
+  const stmt = db.prepare('SELECT parent_id, status FROM main.todos WHERE id = ?');
+  const update = db.prepare("UPDATE main.todos SET status = 'in_progress' WHERE id = ? AND status = 'open'");
+  let cur = stmt.get(todoId);
+  while (cur && cur.parent_id != null) {
+    update.run(cur.parent_id);
+    cur = stmt.get(cur.parent_id);
+  }
+}
+
+// DFS-find next actionable node starting at/after `fromId`.
+// Order: first open child → next open sibling → next open uncle (walk up).
+function findNextOpen(db, fromId) {
+  const childOf = (pid) => db.prepare(
+    `SELECT id FROM main.todos
+     WHERE ${pid == null ? 'parent_id IS NULL' : 'parent_id = ?'}
+       AND status IN ('open', 'in_progress')
+     ORDER BY position, id`
+  ).all(...(pid == null ? [] : [pid]));
+
+  if (fromId == null) {
+    const roots = childOf(null);
+    return roots[0]?.id ?? null;
+  }
+
+  const children = childOf(fromId);
+  if (children.length > 0) return children[0].id;
+
+  let curId = fromId;
+  while (curId != null) {
+    const cur = db.prepare('SELECT parent_id, position FROM main.todos WHERE id = ?').get(curId);
+    if (!cur) return null;
+    const sibling = db.prepare(
+      `SELECT id FROM main.todos
+       WHERE ${cur.parent_id == null ? 'parent_id IS NULL' : 'parent_id = ?'}
+         AND (position > ? OR (position = ? AND id > ?))
+         AND status IN ('open', 'in_progress')
+       ORDER BY position, id LIMIT 1`
+    ).get(...(cur.parent_id == null ? [cur.position, cur.position, curId] : [cur.parent_id, cur.position, cur.position, curId]));
+    if (sibling) return sibling.id;
+    curId = cur.parent_id;
+  }
+  return null;
+}
+
+function renderTree(db, { compact = false } = {}) {
+  const all = db.prepare(
+    'SELECT id, parent_id, position, status, kind, text FROM main.todos ORDER BY IFNULL(parent_id, -1), position, id'
+  ).all();
+  if (all.length === 0) return '(no todos)';
+
+  const cursor = getCursor(db);
+  const childrenByParent = new Map();
+  for (const t of all) {
+    const key = t.parent_id ?? null;
+    if (!childrenByParent.has(key)) childrenByParent.set(key, []);
+    childrenByParent.get(key).push(t);
+  }
+
+  const lines = [];
+  const visit = (parentId, depth) => {
+    const kids = childrenByParent.get(parentId) || [];
+    for (const t of kids) {
+      const box = STATUS_BOX[t.status] || '[?]';
+      const arrow = cursor === t.id ? ' →' : '';
+      const tag = compact ? '' : ` (id:${t.id}${t.kind !== 'TODO' ? `, ${t.kind}` : ''})`;
+      lines.push(`${'  '.repeat(depth)}${box}${arrow} ${t.text}${tag}`);
+      visit(t.id, depth + 1);
+    }
+  };
+  visit(null, 0);
+  return lines.join('\n');
+}
+
+function nextPosition(db, parentId) {
+  const row = db.prepare(
+    `SELECT COALESCE(MAX(position), -1) + 1 AS next FROM main.todos
+     WHERE ${parentId == null ? 'parent_id IS NULL' : 'parent_id = ?'}`
+  ).get(...(parentId == null ? [] : [parentId]));
+  return row.next;
+}
+
 export async function todos(db, args = {}) {
-  const { text, id, status, source } = args;
+  const { text, id, status, source, parent, position } = args;
   const action = args.action ?? 'list';
   const kind = args.kind;
 
@@ -13,9 +118,9 @@ export async function todos(db, args = {}) {
       if (status) { query += ' AND status = ?'; params.push(status); }
       if (source) { query += ' AND source = ?'; params.push(source); }
       if (kind)   { query += ' AND kind = ?';   params.push(kind.toUpperCase()); }
-      query += ' ORDER BY CASE status WHEN \'open\' THEN 0 ELSE 1 END, source, file, line';
+      query += ' ORDER BY CASE status WHEN \'open\' THEN 0 WHEN \'in_progress\' THEN 0 ELSE 1 END, source, file, line';
       const rows = db.prepare(query).all(...params);
-      const open = rows.filter(r => r.status === 'open').length;
+      const open = rows.filter(r => r.status === 'open' || r.status === 'in_progress').length;
       const done = rows.filter(r => r.status === 'done').length;
       return {
         content: [{
@@ -25,12 +130,34 @@ export async function todos(db, args = {}) {
       };
     }
 
+    case 'tree': {
+      const compact = args.compact === true;
+      const tree = renderTree(db, { compact });
+      const cursor = getCursor(db);
+      const cursorRow = cursor ? db.prepare('SELECT id, text FROM main.todos WHERE id = ?').get(cursor) : null;
+      const next = findNextOpen(db, cursor);
+      const nextRow = next ? db.prepare('SELECT id, text FROM main.todos WHERE id = ?').get(next) : null;
+      const summary = [
+        cursorRow ? `Current: (id:${cursorRow.id}) ${cursorRow.text}` : 'Current: (no cursor set)',
+        nextRow && (!cursorRow || nextRow.id !== cursorRow.id) ? `Next: (id:${nextRow.id}) ${nextRow.text}` : '',
+      ].filter(Boolean).join('\n');
+      return {
+        content: [{ type: 'text', text: `${tree}\n\n${summary}` }],
+      };
+    }
+
     case 'add': {
       if (!text) throw new Error('text is required for add action');
       const todoKind = (kind || 'TODO').toUpperCase();
+      const parentId = parent ?? null;
+      if (parentId != null) {
+        const exists = db.prepare('SELECT id FROM main.todos WHERE id = ?').get(parentId);
+        if (!exists) throw new Error(`Parent todo id ${parentId} does not exist`);
+      }
+      const pos = position ?? nextPosition(db, parentId);
       const result = db.prepare(
-        'INSERT INTO main.todos (source, kind, text) VALUES (?, ?, ?)'
-      ).run('manual', todoKind, text);
+        'INSERT INTO main.todos (source, kind, text, parent_id, position) VALUES (?, ?, ?, ?, ?)'
+      ).run('manual', todoKind, text, parentId, pos);
       const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(result.lastInsertRowid);
       return {
         content: [{ type: 'text', text: JSON.stringify({ added: todo }, null, 2) }],
@@ -43,9 +170,63 @@ export async function todos(db, args = {}) {
         'UPDATE main.todos SET status = ?, resolved_at = datetime(\'now\') WHERE id = ?'
       ).run('done', id);
       if (updated.changes === 0) throw new Error(`No todo found with id ${id}`);
+      const cursor = getCursor(db);
+      let advanced = null;
+      if (cursor === id) {
+        const next = findNextOpen(db, id);
+        if (next) { setCursor(db, next); advanced = next; }
+        else clearCursor(db);
+      }
+      const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ resolved: todo, cursor_advanced_to: advanced }, null, 2) }],
+      };
+    }
+
+    case 'focus': {
+      if (!id) throw new Error('id is required for focus action');
+      const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
+      if (!todo) throw new Error(`No todo found with id ${id}`);
+      setCursor(db, id);
+      db.prepare("UPDATE main.todos SET status = 'in_progress' WHERE id = ? AND status = 'open'").run(id);
+      propagateInProgressUp(db, id);
+      const refreshed = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ focused: refreshed }, null, 2) }],
+      };
+    }
+
+    case 'next': {
+      const cursor = getCursor(db);
+      const next = findNextOpen(db, cursor);
+      if (next == null) {
+        clearCursor(db);
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ cursor: null, message: 'No open todos remaining.' }, null, 2) }],
+        };
+      }
+      setCursor(db, next);
+      propagateInProgressUp(db, next);
+      const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(next);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ cursor: next, todo }, null, 2) }],
+      };
+    }
+
+    case 'set_status': {
+      if (!id) throw new Error('id is required for set_status action');
+      if (!status) throw new Error('status is required for set_status action');
+      if (!VALID_STATUS.has(status)) {
+        throw new Error(`Invalid status "${status}". Use: open, in_progress, done, blocked`);
+      }
+      const resolvedAt = status === 'done' ? "datetime('now')" : 'NULL';
+      const updated = db.prepare(
+        `UPDATE main.todos SET status = ?, resolved_at = ${resolvedAt} WHERE id = ?`
+      ).run(status, id);
+      if (updated.changes === 0) throw new Error(`No todo found with id ${id}`);
       const todo = db.prepare('SELECT * FROM main.todos WHERE id = ?').get(id);
       return {
-        content: [{ type: 'text', text: JSON.stringify({ resolved: todo }, null, 2) }],
+        content: [{ type: 'text', text: JSON.stringify({ updated: todo }, null, 2) }],
       };
     }
 
@@ -53,7 +234,7 @@ export async function todos(db, args = {}) {
       const files = await walkRepo(process.cwd());
       const found = await scanTodos(db, files);
       const open = db.prepare(
-        'SELECT COUNT(*) AS n FROM main.todos WHERE status = \'open\''
+        'SELECT COUNT(*) AS n FROM main.todos WHERE status IN (\'open\', \'in_progress\')'
       ).get().n;
       return {
         content: [{
@@ -64,6 +245,6 @@ export async function todos(db, args = {}) {
     }
 
     default:
-      throw new Error(`Unknown action: "${action}". Use list, add, resolve, or scan.`);
+      throw new Error(`Unknown action: "${action}". Use list, tree, add, resolve, focus, next, set_status, or scan.`);
   }
 }