@misterhuydo/cairn-mcp 1.9.0 → 1.12.0

package/README.md

@@ -46,8 +46,8 @@ No need to re-run `cairn install` — hooks and MCP config carry over between ve
 |---|---|---|
 | `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` |
+| `Stop` | End of every response | Session auto-saved to `.cairn/session.json`, Claude auto-memory backed up to `.cairn/memory/`, and the roadmap re-surfaced — all confirmed in one line |
+| `UserPromptSubmit` | First message of a new session | Fresh project: Claude prompted to run `cairn_maintain`. Returning session: Claude prompted to run `cairn_resume`. Memory restored from `.cairn/memory/` if the Claude store is empty (new machine / fresh clone) |
 
 ---
 

package/bin/cairn-cli.js

@@ -9,154 +9,193 @@ import { minifyVue } from '../src/bundler/vueMinifier.js';
 import { checkpoint } from '../src/tools/checkpoint.js';
 import { findCairnDir, getTempPath, loadMap, saveMap, validateMap, OUTLINE_THRESHOLD } from '../src/tools/minifyMap.js';
 import { generateOutline } from '../src/bundler/outliner.js';
+import { claudeSlug } from '../src/graph/cwd.js';
 
 const MINIFY_LANGS = new Set(['java', 'typescript', 'javascript', 'vue', 'python', 'sql']);
 
-// 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 = `#!/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; }
+// ── Memory sync (Claude auto-memory is canonical; .cairn/memory is the backup) ──
+// Resolve the Claude Code auto-memory dir for a project cwd, or null when this
+// isn't a Claude Code project (no projects/<slug> dir) — callers then no-op.
+function claudeMemoryDirFor(cwd) {
+  const projDir = path.join(os.homedir(), '.claude', 'projects', claudeSlug(cwd));
+  if (!fs.existsSync(projDir)) return null;
+  return path.join(projDir, 'memory');
+}
+function listMd(dir) {
+  try { return fs.readdirSync(dir).filter(f => f.endsWith('.md')); } catch { return []; }
+}
+// Backup: Claude store -> .cairn/memory (flat, add/update only, mtime-preserving).
+// Never deletes from the backup — a backup is a superset, so an intentional
+// Claude-side deletion doesn't erase history. Returns count of files written.
+function backupMemory(cwd) {
+  const claudeDir = claudeMemoryDirFor(cwd);
+  if (!claudeDir || !fs.existsSync(claudeDir)) return 0;
+  const backupDir = path.join(cwd, '.cairn', 'memory');
+  fs.mkdirSync(backupDir, { recursive: true });
+  let n = 0;
+  for (const f of listMd(claudeDir)) {
+    const src = path.join(claudeDir, f);
+    let st; try { st = fs.statSync(src); } catch { continue; }
+    if (!st.isFile()) continue;
+    const dst = path.join(backupDir, f);
+    let need = !fs.existsSync(dst);
+    if (!need) { try { need = st.mtimeMs > fs.statSync(dst).mtimeMs; } catch { need = true; } }
+    if (need) {
+      fs.copyFileSync(src, dst);
+      try { fs.utimesSync(dst, st.atime, st.mtime); } catch {}
+      n++;
+    }
+  }
+  return n;
+}
+// Restore: .cairn/memory -> Claude store, ONLY when the Claude store is empty
+// (new machine / fresh clone / user wiped ~/.claude/projects). Returns count.
+function restoreMemoryIfEmpty(cwd) {
+  const claudeDir = claudeMemoryDirFor(cwd);
+  if (!claudeDir) return 0;
+  fs.mkdirSync(claudeDir, { recursive: true });
+  if (listMd(claudeDir).some(f => f !== 'MEMORY.md')) return 0; // already populated
+  const backupDir = path.join(cwd, '.cairn', 'memory');
+  if (!fs.existsSync(backupDir)) return 0;
+  let n = 0;
+  for (const f of fs.readdirSync(backupDir)) {
+    const src = path.join(backupDir, 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 {}
+    fs.copyFileSync(src, path.join(claudeDir, f));
+    try { fs.utimesSync(path.join(claudeDir, f), st.atime, st.mtime); } catch {}
+    n++;
   }
-});
-`;
-
-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 {}
+  return n;
 }
 
-// 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++;
+// ── Roadmap view (shared by `session-tick` and `roadmap-hint`) ──
+// Returns { active, currentLabel, treeLines, advanced, memoLines } reading the
+// roadmap_phases tree + cursor. active=false when no DB / no cursor.
+async function roadmapView(cairnDir) {
+  const inactive = { active: false };
+  const dbPath = path.join(cairnDir, 'index.db');
+  if (!fs.existsSync(dbPath)) return inactive;
+  let DatabaseSync;
+  try { ({ DatabaseSync } = await import('node:sqlite')); } catch { return inactive; }
+  let db;
+  try { db = new DatabaseSync(dbPath, { readonly: true }); } catch { return inactive; }
+
+  const slugify = (n) => n.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
+  function extractPhaseSection(memoPath, phaseNumber) {
+    if (!fs.existsSync(memoPath)) return null;
+    const raw = fs.readFileSync(memoPath, 'utf8');
+    let inPhasesSection = false, collecting = false;
+    const acc = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (/^##\s+Phases\s*$/i.test(line)) { inPhasesSection = true; continue; }
+      if (inPhasesSection && /^##\s+/.test(line) && !/^###/.test(line)) break;
+      if (!inPhasesSection) continue;
+      const m = /^###\s+Phase\s+(\d+)\s*:\s*(.+?)\s*$/.exec(line);
+      if (m) {
+        if (collecting) break;
+        if (parseInt(m[1], 10) === phaseNumber) { acc.push(`### Phase ${m[1]}: ${m[2]}`); collecting = true; }
+        continue;
+      }
+      if (collecting) acc.push(line);
     }
+    return acc.join('\n').trim() || null;
   }
-}
-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++;
+  try {
+    const cursorRow = db.prepare("SELECT phase_id FROM roadmap_cursor WHERE singleton = 1").get();
+    const cursorId = cursorRow?.phase_id ?? null;
+    if (cursorId == null) { db.close(); return inactive; }
+    const all = db.prepare(
+      'SELECT id, decision_name, phase_number, parent_phase_id, text, status, position FROM roadmap_phases ORDER BY decision_name, phase_number, position, id'
+    ).all();
+
+    const STATUS_BOX = { open: '[ ]', in_progress: '[~]', done: '[x]', blocked: '[!]', stale: '[s]' };
+    const byParent = new Map();
+    for (const p of all) {
+      const k = p.parent_phase_id ?? 'root';
+      if (!byParent.has(k)) byParent.set(k, []);
+      byParent.get(k).push(p);
     }
-    if (restored > 0) {
-      process.stdout.write(\`[cairn] Restored \${restored} memory files from .cairn/memory/auto-memory/ (new project location detected)\\n\`);
+    for (const arr of byParent.values()) {
+      arr.sort((a, b) => {
+        if (a.decision_name && b.decision_name && a.decision_name !== b.decision_name) return a.decision_name.localeCompare(b.decision_name);
+        if (a.phase_number != null && b.phase_number != null) return a.phase_number - b.phase_number;
+        return a.position - b.position || a.id - b.id;
+      });
+    }
+    const roots = byParent.get('root') || [];
+    const decisionRoots = new Map();
+    for (const r of roots) {
+      if (r.decision_name == null) continue;
+      if (!decisionRoots.has(r.decision_name)) decisionRoots.set(r.decision_name, []);
+      decisionRoots.get(r.decision_name).push(r);
+    }
+    const lines = [];
+    const visitSubtree = (parentId, depth) => {
+      for (const p of byParent.get(parentId) || []) {
+        if (p.status === 'stale') continue;
+        const arrow = cursorId === p.id ? ' →' : '';
+        const label = p.phase_number != null ? `Phase ${p.phase_number}: ${p.text}` : p.text;
+        lines.push(`${'  '.repeat(depth)}${STATUS_BOX[p.status] || '[?]'}${arrow} ${label}`);
+        visitSubtree(p.id, depth + 1);
+      }
+    };
+    for (const [decisionName, phases] of decisionRoots) {
+      const live = phases.filter(p => p.status !== 'stale');
+      if (live.length === 0) continue;
+      const allDone = live.every(p => p.status === 'done');
+      const anyInProg = live.some(p => p.status === 'in_progress');
+      const rootStatus = allDone ? 'done' : (anyInProg ? 'in_progress' : 'open');
+      const doneCount = live.filter(p => p.status === 'done').length;
+      lines.push(`${STATUS_BOX[rootStatus]} Decision: ${decisionName} (${doneCount}/${live.length} done)`);
+      for (const p of phases) {
+        if (p.status === 'stale') continue;
+        const arrow = cursorId === p.id ? ' →' : '';
+        lines.push(`  ${STATUS_BOX[p.status] || '[?]'}${arrow} Phase ${p.phase_number}: ${p.text}`);
+        visitSubtree(p.id, 2);
+      }
     }
-  }
-}
 
-// 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++;
+    const findById = (id) => all.find(p => p.id === id);
+    const cursorNode = findById(cursorId);
+    let rootDecision = cursorNode?.decision_name ?? null;
+    let rootPhaseNum = cursorNode?.phase_number ?? null;
+    let walker = cursorNode;
+    while (walker && walker.parent_phase_id != null) {
+      walker = findById(walker.parent_phase_id);
+      if (!walker) break;
+      rootDecision = walker.decision_name ?? rootDecision;
+      rootPhaseNum = walker.phase_number ?? rootPhaseNum;
+    }
+    db.close();
+
+    const currentLabel = cursorNode
+      ? (cursorNode.phase_number != null
+          ? `${cursorNode.decision_name} / Phase ${cursorNode.phase_number}: ${cursorNode.text}`
+          : `${rootDecision} / Phase ${rootPhaseNum} → ${cursorNode.text}`)
+      : '(unknown)';
+
+    // Advance detection via state file
+    const stateFile = path.join(cairnDir, '.last-roadmap-cursor');
+    let lastCursor = null;
+    try { lastCursor = parseInt(fs.readFileSync(stateFile, 'utf8').trim(), 10); } catch {}
+    const advanced = lastCursor !== cursorId;
+    try { fs.writeFileSync(stateFile, String(cursorId), 'utf8'); } catch {}
+
+    let memoLines = null;
+    if (advanced && rootDecision != null && rootPhaseNum != null) {
+      const memoPath = path.join(cairnDir, 'memory', `decision_${slugify(rootDecision)}.md`);
+      const section = extractPhaseSection(memoPath, rootPhaseNum);
+      if (section) memoLines = section.split('\n');
+    }
+    return { active: true, currentLabel, treeLines: lines, advanced, memoLines };
+  } catch (e) {
+    try { db?.close(); } catch {}
+    return inactive;
   }
 }
-if (synced > 0) {
-  process.stdout.write(\`[cairn] Synced \${synced} memory file(s) from .cairn/memory/ to Claude memory dir\\n\`);
-}
-`;
 
 process.on('uncaughtException', (e) => {
   process.stderr.write(`cairn: ${e.message}\n`);
@@ -405,6 +444,72 @@ if (subcommand === '--version' || subcommand === '-v') {
   checkpoint(null, { message, active_files: activeFiles, notes: existingNotes });
   process.exit(0);
 
+} else if (subcommand === 'session-tick') {
+  // Stop hook: end-of-turn heartbeat. Saves a checkpoint, backs up the Claude
+  // auto-memory store -> .cairn/memory, and re-surfaces the roadmap. Stop-hook
+  // stdout is invisible to the user, so everything is surfaced via JSON:
+  //   systemMessage      -> one-line confirmation (checkpoint · memory · roadmap)
+  //   additionalContext  -> full roadmap tree (+ current-phase memo on advance)
+  const cwd = process.cwd();
+  const cairnDir = path.join(cwd, '.cairn');
+  if (!fs.existsSync(cairnDir)) process.exit(0);
+
+  const seg = [];
+
+  // 1. checkpoint (silent)
+  try {
+    const message = `Auto-checkpoint at ${new Date().toISOString()}`;
+    let existingNotes = [];
+    const sessionPath = path.join(cairnDir, 'session.json');
+    if (fs.existsSync(sessionPath)) {
+      try { existingNotes = JSON.parse(fs.readFileSync(sessionPath, 'utf8')).notes || []; } catch {}
+    }
+    const map = loadMap(cairnDir);
+    const activeFiles = Object.entries(map).filter(([, e]) => (e.readCount ?? 0) > 0).map(([p]) => p);
+    checkpoint(null, { message, active_files: activeFiles, notes: existingNotes });
+    seg.push('✓ checkpoint saved');
+  } catch {}
+
+  // 2. memory backup: Claude store -> .cairn/memory
+  try {
+    const n = backupMemory(cwd);
+    if (n > 0) seg.push(`memory backed up (${n})`);
+  } catch {}
+
+  // 3. roadmap re-surface (read-only; content changes happen via cairn_roadmap)
+  let additionalContext = '';
+  try {
+    const rv = await roadmapView(cairnDir);
+    if (rv.active) {
+      seg.push(`roadmap ${rv.advanced ? 'updated' : 'on track'}: ${rv.currentLabel}`);
+      const ctx = ['[cairn] Production roadmap (→ = cursor / current phase):', ...rv.treeLines.map(l => '  ' + l)];
+      if (rv.memoLines) {
+        ctx.push('', '── Decision memo (current phase) ──', ...rv.memoLines,
+                 '── (re-read after each phase to confirm direction) ──');
+      }
+      ctx.push('', 'Keep this current via cairn_roadmap on MATERIAL change (phase done / blocked / new) — not every turn.');
+      additionalContext = ctx.join('\n');
+    }
+  } catch {}
+
+  if (seg.length === 0) process.exit(0);
+  const out = { systemMessage: `[cairn] ${seg.join(' · ')}` };
+  if (additionalContext) out.additionalContext = additionalContext;
+  process.stdout.write(JSON.stringify(out));
+  process.exit(0);
+
+} else if (subcommand === 'memory-restore') {
+  // UserPromptSubmit hook: restore .cairn/memory -> Claude store ONLY when the
+  // Claude store is empty (new machine / fresh clone / wiped ~/.claude/projects).
+  // One-way, non-destructive. UserPromptSubmit stdout IS visible to the user.
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, '.cairn'))) process.exit(0);
+  try {
+    const n = restoreMemoryIfEmpty(cwd);
+    if (n > 0) process.stdout.write(`[cairn] Restored ${n} memory file(s) from .cairn/memory backup (Claude store was empty)\n`);
+  } catch {}
+  process.exit(0);
+
 } else if (subcommand === 'resume-hint') {
   const cairnDir = path.join(process.cwd(), '.cairn');
   const sessionPath = path.join(cairnDir, 'session.json');
@@ -537,79 +642,24 @@ if (subcommand === '--version' || subcommand === '-v') {
   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.
+  // Manual/legacy: print the roadmap tree to stdout when a cursor is active.
+  // The end-of-turn Stop hook now uses `session-tick`, which surfaces the same
+  // view via JSON (Stop-hook stdout is invisible to the user). Shares roadmapView.
   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 {}
+  const rv = await roadmapView(cairnDir);
+  if (!rv.active) process.exit(0);
+  const out = [
+    '[cairn] ROADMAP — cursor is active.',
+    ...rv.treeLines.map(l => '[cairn]   ' + l),
+    `[cairn] Current: ${rv.currentLabel}`,
+  ];
+  if (rv.memoLines) {
+    out.push('[cairn] ───── Decision memo (current phase) ─────');
+    for (const ln of rv.memoLines) out.push('[cairn] ' + ln);
+    out.push('[cairn] ───── (re-read after each phase to confirm direction) ─────');
   }
+  out.push('[cairn] Use cairn_roadmap set_status <id> done (auto-advances), focus <id>, or next to move cursor.');
+  process.stdout.write(out.join('\n') + '\n');
   process.exit(0);
 
 } else if (subcommand === 'install') {
@@ -642,11 +692,9 @@ 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.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('  Stop                 -> cairn session-tick             (checkpoint + memory backup + roadmap, surfaced)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
-  console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
+  console.log('  UserPromptSubmit     -> cairn memory-restore            (restore .cairn/memory -> Claude store if empty)');
   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');
@@ -665,19 +713,13 @@ 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)');
-  if (isGlobal) {
-    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('  Stop                 -> cairn session-tick             (checkpoint + memory backup + roadmap, surfaced)');
   console.log('  UserPromptSubmit     -> cairn resume-hint               (remind Claude of prior session)');
-  if (isGlobal) {
-    console.log('  UserPromptSubmit     -> sync-memory-restore.mjs         (sync .cairn/memory/ -> ~/.claude/memory, mtime-based)');
-  }
+  console.log('  UserPromptSubmit     -> cairn memory-restore            (restore .cairn/memory -> Claude store if empty)');
   process.exit(0);
 
 } else {
-  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | resume-hint | roadmap-hint>');
+  console.error('Usage: cairn <--version | install | install-hooks [--global] | minify | edit-guard | validate-map | checkpoint --auto | session-tick | resume-hint | roadmap-hint | memory-restore>');
   process.exit(1);
 }
 
@@ -706,69 +748,52 @@ function applyHooks(settingsDir, isGlobal) {
   }
   settings.hooks.PreToolUse = cleanedPreHooks;
 
-  // Stop: cairn checkpoint --auto
-  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' }] });
-  }
-  // 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' }] });
+  // Helper: drop hooks whose command matches a predicate, then prune empty entries.
+  const stripHooks = (entries, pred) => (entries || [])
+    .map(entry => ({ ...entry, hooks: (entry.hooks || []).filter(h => !pred(h.command)) }))
+    .filter(entry => (entry.hooks || []).length > 0);
+  // Legacy deployed memory-sync scripts (forward/restore, .mjs or .py) from prior installs.
+  const isLegacyMemoryScript = (cmd) => typeof cmd === 'string' &&
+    /sync-memory-(forward|restore)\.(mjs|py)/.test(cmd);
+
+  // Stop: single end-of-turn heartbeat. Migrate away from the old split hooks
+  // (checkpoint --auto + roadmap-hint) — both wrote to Stop-hook stdout, which
+  // Claude Code never surfaces. `session-tick` checkpoints, backs up memory, and
+  // re-surfaces the roadmap via JSON systemMessage/additionalContext.
+  let stopHooks = stripHooks(settings.hooks.Stop, (cmd) =>
+    cmd === 'cairn checkpoint --auto' || cmd === 'cairn roadmap-hint');
+  if (!stopHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn session-tick'))) {
+    stopHooks.push({ hooks: [{ type: 'command', command: 'cairn session-tick' }] });
   }
   settings.hooks.Stop = stopHooks;
 
-  // UserPromptSubmit: cairn resume-hint
-  let submitHooks = settings.hooks.UserPromptSubmit || [];
+  // UserPromptSubmit: resume-hint + memory-restore (restore .cairn/memory -> Claude
+  // store only when the Claude store is empty). Strip the old deployed restore script.
+  let submitHooks = stripHooks(settings.hooks.UserPromptSubmit, isLegacyMemoryScript);
   if (!submitHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn resume-hint'))) {
     submitHooks.push({ hooks: [{ type: 'command', command: 'cairn resume-hint' }] });
   }
+  if (!submitHooks.some(h => h.hooks?.some(hh => hh.command === 'cairn memory-restore'))) {
+    submitHooks.push({ hooks: [{ type: 'command', command: 'cairn memory-restore' }] });
+  }
+  settings.hooks.UserPromptSubmit = submitHooks;
+
+  // PostToolUse: drop the legacy forward-sync hook entirely. The Stop-hook backup
+  // (session-tick) now captures Claude auto-memory writes into .cairn/memory.
+  const cleanedPost = stripHooks(settings.hooks.PostToolUse, isLegacyMemoryScript);
+  if (cleanedPost.length > 0) settings.hooks.PostToolUse = cleanedPost;
+  else delete settings.hooks.PostToolUse;
 
   if (isGlobal) {
-    // Deploy memory sync scripts to ~/.claude/scripts/ (Node — cross-platform, no python3 required)
+    // Remove obsolete deployed sync scripts from prior installs.
     const scriptsDir = path.join(settingsDir, 'scripts');
-    fs.mkdirSync(scriptsDir, { recursive: true });
-    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']) {
+    for (const legacy of ['sync-memory-forward.mjs', 'sync-memory-restore.mjs',
+                          '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 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/
-    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 }] });
-    }
   }
 
-  settings.hooks.UserPromptSubmit = submitHooks;
-
   // Write .cairn-project sentinel for project-scoped installs
   if (!isGlobal) {
     const cairnDir = path.join(process.cwd(), '.cairn');