dual-brain 0.2.4 → 0.2.5

package/bin/dual-brain.mjs

@@ -242,11 +242,19 @@ Commands:
   init                      First-time setup → flows into interactive REPL
   auth                      Show provider login and plan status
   install                   Install Claude Code hooks into the current project
+  install --global          Write hooks into ~/.claude/settings.json (absolute paths,
+                            fires from any working directory after shell restart)
+  uninstall --global        Remove dual-brain hooks from ~/.claude/settings.json
   go "task description"     Detect → decide → dispatch (alias for do)
     --dry-run               Show routing decision without executing
     --files a.mjs,b.mjs     Provide file context for risk classification
     --verbose, -v           Print routing trace (intent, risk, health, model selection)
   think "question"          Multi-round architecture decision with dual-brain
+  pr                        Show PR status for current branch
+  pr create                 Create PR from current branch with auto-generated description
+    --draft                 Create as a draft PR
+  pr list                   List open PRs (--closed, --all for other states)
+  pr view <N>               View PR #N details
   status                    Provider health, session stats, available models
     --verbose, -v           Also print profile file path and raw profile object
   hot <provider>            Manually mark all model classes for provider as hot
@@ -373,6 +381,26 @@ async function cmdInit(rl) {
   // --- Step 2b: Install hooks ---
   await cmdInstall(cwd);
 
+  // --- Step 2c: Suggest global install if not already done ---
+  try {
+    const { homedir } = await import('node:os');
+    const globalSettingsPath = join(homedir(), '.claude', 'settings.json');
+    const DB_MARKER = '# dual-brain-managed';
+    let alreadyGlobal = false;
+    if (existsSync(globalSettingsPath)) {
+      try {
+        const gs = JSON.parse(readFileSync(globalSettingsPath, 'utf8'));
+        const allHooks = [...(gs.hooks?.PreToolUse || []), ...(gs.hooks?.PostToolUse || [])];
+        alreadyGlobal = allHooks.some(e => e.hooks?.some(h => h.command?.includes(DB_MARKER)));
+      } catch {}
+    }
+    if (!alreadyGlobal) {
+      console.log('');
+      console.log('  Tip: run "dual-brain install --global" to load these hooks from');
+      console.log('  any directory — so dual-brain works when Replit restarts a shell.');
+    }
+  } catch {}
+
   // --- Step 3: Show dashboard ---
   console.log('');
   const repo    = loadRepoCache(cwd);
@@ -991,6 +1019,139 @@ async function cmdInstall(cwd) {
   }
 }
 
+async function installGlobal() {
+  const { homedir } = await import('node:os');
+  const globalClaudeDir = join(homedir(), '.claude');
+  const globalSettingsPath = join(globalClaudeDir, 'settings.json');
+
+  // Resolve absolute path to hooks directory via import.meta.url
+  const pkgRoot = join(__dirname, '..');
+  const hooksDir = join(pkgRoot, '.claude', 'hooks');
+
+  // Warn if running from npx (ephemeral path)
+  if (pkgRoot.includes('.npm/_npx') || pkgRoot.includes('npx-')) {
+    console.log('  Warning: Running from npx — paths will break after this session.');
+    console.log('    Install globally first: npm i -g dual-brain');
+    console.log('    Then run: dual-brain install --global');
+    return;
+  }
+
+  // Verify hooks exist at resolved path
+  if (!existsSync(join(hooksDir, 'head-guard.mjs'))) {
+    console.log('  Error: Could not resolve hook files at: ' + hooksDir);
+    return;
+  }
+
+  // Load existing settings (merge, never clobber)
+  let existing = {};
+  if (existsSync(globalSettingsPath)) {
+    try { existing = JSON.parse(readFileSync(globalSettingsPath, 'utf8')); } catch {}
+  }
+
+  // Ensure hooks structure exists
+  if (!existing.hooks) existing.hooks = {};
+  if (!existing.hooks.PreToolUse) existing.hooks.PreToolUse = [];
+  if (!existing.hooks.PostToolUse) existing.hooks.PostToolUse = [];
+
+  // Define dual-brain hooks with ownership marker
+  const DB_MARKER = '# dual-brain-managed';
+  const preToolHooks = [
+    { matcher: 'Edit',        hooks: [{ type: 'command', command: `node ${join(hooksDir, 'head-guard.mjs')} ${DB_MARKER}` }] },
+    { matcher: 'Write',       hooks: [{ type: 'command', command: `node ${join(hooksDir, 'head-guard.mjs')} ${DB_MARKER}` }] },
+    { matcher: 'NotebookEdit',hooks: [{ type: 'command', command: `node ${join(hooksDir, 'head-guard.mjs')} ${DB_MARKER}` }] },
+    { matcher: 'Bash',        hooks: [{ type: 'command', command: `node ${join(hooksDir, 'head-guard.mjs')} ${DB_MARKER}` }] },
+    { matcher: 'Agent',       hooks: [{ type: 'command', command: `node ${join(hooksDir, 'enforce-tier.mjs')} ${DB_MARKER}` }] },
+  ];
+  const postToolHooks = [
+    { matcher: '', hooks: [{ type: 'command', command: `node ${join(hooksDir, 'cost-logger.mjs')} ${DB_MARKER}` }] },
+    { matcher: '', hooks: [{ type: 'command', command: `node ${join(hooksDir, 'auto-update-wrapper.mjs')} ${DB_MARKER}` }] },
+  ];
+
+  // Remove any existing dual-brain hooks (idempotent)
+  const isDBHook = (entry) => entry.hooks?.some(h => h.command?.includes(DB_MARKER));
+  existing.hooks.PreToolUse  = existing.hooks.PreToolUse.filter(e => !isDBHook(e));
+  existing.hooks.PostToolUse = existing.hooks.PostToolUse.filter(e => !isDBHook(e));
+
+  // Add dual-brain hooks
+  existing.hooks.PreToolUse.push(...preToolHooks);
+  existing.hooks.PostToolUse.push(...postToolHooks);
+
+  // Write merged settings
+  mkdirSync(globalClaudeDir, { recursive: true });
+  writeFileSync(globalSettingsPath, JSON.stringify(existing, null, 2) + '\n');
+
+  // Write minimal global CLAUDE.md (only if none exists, or append section)
+  const globalClaudeMd = join(globalClaudeDir, 'CLAUDE.md');
+  const dbSection = `\n## Dual-Brain Global Hooks\n\nThis machine has dual-brain hooks installed globally.\nProject-local .claude/CLAUDE.md and settings take precedence.\nManaged by: dual-brain install --global\n`;
+
+  if (!existsSync(globalClaudeMd)) {
+    writeFileSync(globalClaudeMd, dbSection);
+  } else {
+    const content = readFileSync(globalClaudeMd, 'utf8');
+    if (!content.includes('Dual-Brain Global Hooks')) {
+      writeFileSync(globalClaudeMd, content + '\n' + dbSection);
+    }
+  }
+
+  console.log('  + dual-brain hooks installed globally');
+  console.log('    hooks dir: ' + hooksDir);
+  console.log('    settings:  ' + globalSettingsPath);
+  console.log('');
+  console.log('  All new Claude sessions will load dual-brain hooks.');
+  console.log('  Run "dual-brain uninstall --global" to remove.');
+}
+
+async function uninstallGlobal() {
+  const { homedir } = await import('node:os');
+  const globalSettingsPath = join(homedir(), '.claude', 'settings.json');
+
+  if (!existsSync(globalSettingsPath)) {
+    console.log('  No global settings found.');
+    return;
+  }
+
+  let settings = {};
+  try { settings = JSON.parse(readFileSync(globalSettingsPath, 'utf8')); } catch { return; }
+
+  const DB_MARKER = '# dual-brain-managed';
+  const isDBHook = (entry) => entry.hooks?.some(h => h.command?.includes(DB_MARKER));
+
+  let removed = 0;
+  if (settings.hooks?.PreToolUse) {
+    const before = settings.hooks.PreToolUse.length;
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(e => !isDBHook(e));
+    removed += before - settings.hooks.PreToolUse.length;
+  }
+  if (settings.hooks?.PostToolUse) {
+    const before = settings.hooks.PostToolUse.length;
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(e => !isDBHook(e));
+    removed += before - settings.hooks.PostToolUse.length;
+  }
+
+  // Clean up empty arrays/objects
+  if (settings.hooks?.PreToolUse?.length === 0)  delete settings.hooks.PreToolUse;
+  if (settings.hooks?.PostToolUse?.length === 0) delete settings.hooks.PostToolUse;
+  if (Object.keys(settings.hooks || {}).length === 0) delete settings.hooks;
+
+  writeFileSync(globalSettingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+  // Remove dual-brain section from global CLAUDE.md
+  const globalClaudeMd = join(homedir(), '.claude', 'CLAUDE.md');
+  if (existsSync(globalClaudeMd)) {
+    let content = readFileSync(globalClaudeMd, 'utf8');
+    const dbSectionRegex = /\n## Dual-Brain Global Hooks\n[\s\S]*?Managed by: dual-brain install --global\n/;
+    content = content.replace(dbSectionRegex, '');
+    if (content.trim()) {
+      writeFileSync(globalClaudeMd, content);
+    } else {
+      unlinkSync(globalClaudeMd);
+    }
+  }
+
+  console.log(`  - removed ${removed} dual-brain hook${removed === 1 ? '' : 's'} from global settings`);
+  console.log('  Other settings preserved.');
+}
+
 function cmdRemember(text) {
   if (!text) err('Usage: dual-brain remember "preference text"');
   const profile = rememberPreference(text, { scope: 'project', cwd: process.cwd() });
@@ -1050,6 +1211,182 @@ function cmdBreakGlass(reason) {
   console.log('└' + '─'.repeat(inner) + '┘');
 }
 
+// ─── PR command ───────────────────────────────────────────────────────────────
+
+async function cmdPR(args) {
+  const cwd = process.cwd();
+  const sub = args[0] ?? '';
+
+  // Lazy import — only loaded when 'pr' is invoked
+  let prAgent;
+  try {
+    prAgent = await import('../src/pr-agent.mjs');
+  } catch (e) {
+    console.error('pr-agent module not available:', e.message);
+    process.exit(1);
+  }
+
+  const gh = prAgent.hasGitHub();
+  if (!gh.available) {
+    console.error('gh CLI not found. Install GitHub CLI: https://cli.github.com');
+    process.exit(1);
+  }
+
+  // ── dual-brain pr  (show current branch PR status) ──────────────────────────
+  if (!sub || sub === 'status') {
+    if (!gh.authenticated) {
+      console.log('gh CLI is available but not authenticated. Run: gh auth login');
+      return;
+    }
+    const info = prAgent.getBranchInfo(cwd);
+    console.log('\n── PR status ─────────────────────────────────────────────\n');
+    console.log(`  Branch:   ${info.branch ?? '(unknown)'}`);
+    console.log(`  Base:     ${info.defaultBranch}`);
+    console.log(`  Ahead:    ${info.ahead} commit(s)`);
+    console.log(`  Behind:   ${info.behind} commit(s)`);
+
+    if (info.isDefault) {
+      console.log('\n  On default branch — create a feature branch first.');
+      return;
+    }
+
+    // Check for an existing PR on this branch
+    try {
+      const { execSync: _exec } = await import('node:child_process');
+      const json = _exec(`gh pr list --head "${info.branch}" --json number,title,state,url`, {
+        cwd, encoding: 'utf8', timeout: 10000,
+      });
+      const prs = JSON.parse(json);
+      if (prs.length > 0) {
+        const pr = prs[0];
+        console.log(`\n  PR #${pr.number}: ${pr.title}`);
+        console.log(`  State: ${pr.state}`);
+        console.log(`  URL:   ${pr.url}`);
+      } else {
+        console.log('\n  No PR open for this branch.');
+        console.log(`  Create one: dual-brain pr create`);
+      }
+    } catch {
+      console.log('\n  (Could not check for existing PR — run: gh pr status)');
+    }
+    console.log('');
+    return;
+  }
+
+  // ── dual-brain pr list ───────────────────────────────────────────────────────
+  if (sub === 'list') {
+    if (!gh.authenticated) {
+      console.log('gh CLI not authenticated. Run: gh auth login');
+      return;
+    }
+    const state = args.includes('--closed') ? 'closed' : args.includes('--all') ? 'all' : 'open';
+    const prs = prAgent.listPRs(cwd, { state, limit: 20 });
+    if (prs.length === 0) {
+      console.log(`No ${state} PRs found.`);
+      return;
+    }
+    console.log(`\n── ${state} PRs ──────────────────────────────────────────────\n`);
+    for (const pr of prs) {
+      const draft = pr.isDraft ? ' [draft]' : '';
+      const date  = pr.createdAt ? new Date(pr.createdAt).toLocaleDateString() : '';
+      console.log(`  #${pr.number}  ${pr.title}${draft}`);
+      console.log(`       ${pr.headRefName}  by ${pr.author?.login ?? '?'}  ${date}`);
+    }
+    console.log('');
+    return;
+  }
+
+  // ── dual-brain pr view <N> ───────────────────────────────────────────────────
+  if (sub === 'view') {
+    const prNum = args[1];
+    if (!prNum || isNaN(Number(prNum))) {
+      console.error('Usage: dual-brain pr view <PR-number>');
+      process.exit(1);
+    }
+    const details = prAgent.getPRDetails(prNum, cwd);
+    if (!details) {
+      console.error(`PR #${prNum} not found or gh CLI error.`);
+      process.exit(1);
+    }
+    console.log(`\n── PR #${prNum}: ${details.title} ─────────────────────────────\n`);
+    console.log(`  State:    ${details.state}`);
+    console.log(`  Branch:   ${details.headRefName} → ${details.baseRefName}`);
+    console.log(`  Changes:  +${details.additions} -${details.deletions}  (${details.changedFiles} files)`);
+    if (details.statusCheckRollup?.length) {
+      const passing = details.statusCheckRollup.filter(c => c.conclusion === 'SUCCESS').length;
+      const total   = details.statusCheckRollup.length;
+      console.log(`  Checks:   ${passing}/${total} passing`);
+    }
+    if (details.body) {
+      console.log('\n  Body:\n');
+      console.log(details.body.split('\n').map(l => `    ${l}`).join('\n').slice(0, 1500));
+    }
+    console.log('');
+    return;
+  }
+
+  // ── dual-brain pr create ─────────────────────────────────────────────────────
+  if (sub === 'create') {
+    if (!gh.authenticated) {
+      console.log('gh CLI not authenticated. Run: gh auth login');
+      return;
+    }
+    const info = prAgent.getBranchInfo(cwd);
+    if (info.isDefault || !info.branch) {
+      console.error('You are on the default branch. Switch to a feature branch before creating a PR.');
+      process.exit(1);
+    }
+    if (info.ahead === 0) {
+      console.error('No commits ahead of the base branch. Make changes and commit first.');
+      process.exit(1);
+    }
+
+    const diff = prAgent.getDiffSummary(info.defaultBranch, cwd);
+    const draft = args.includes('--draft');
+
+    // Auto-generate a title from the branch name
+    const rawTitle = info.branch.replace(/^db\//, '').replace(/-/g, ' ');
+    const title = rawTitle.charAt(0).toUpperCase() + rawTitle.slice(1);
+
+    // Auto-generate body from diff
+    const body = prAgent.buildPRBody(title, {
+      filesChanged: diff.files,
+    });
+
+    console.log(`\n── Creating PR from ${info.branch} → ${info.defaultBranch} ────────────\n`);
+    console.log(`  Title:  ${title}`);
+    console.log(`  Files:  ${diff.fileCount} changed`);
+    if (diff.summary) console.log(`  Diff:   ${diff.summary}`);
+    if (draft) console.log('  Mode:   draft');
+    console.log('');
+
+    const result = prAgent.createPR({
+      title,
+      body,
+      baseBranch: info.defaultBranch,
+      draft,
+      cwd,
+    });
+
+    if (result.success) {
+      console.log(`  PR created: ${result.url}`);
+    } else {
+      console.error(`  Failed to create PR: ${result.error}`);
+      process.exit(1);
+    }
+    console.log('');
+    return;
+  }
+
+  // Unknown sub-subcommand
+  console.log(`Unknown pr subcommand: "${sub}"`);
+  console.log('Usage:');
+  console.log('  dual-brain pr              Show PR status for current branch');
+  console.log('  dual-brain pr create       Create PR from current branch');
+  console.log('  dual-brain pr list         List open PRs');
+  console.log('  dual-brain pr view <N>     View PR details');
+}
+
 // ─── Screen helpers ───────────────────────────────────────────────────────────
 
 /**
@@ -5640,7 +5977,16 @@ async function main() {
   }
 
   // One-shot commands — run and exit
-  if (cmd === 'install')  { await cmdInstall(); return; }
+  if (cmd === 'install') {
+    if (args.includes('--global')) { await installGlobal(); return; }
+    await cmdInstall();
+    return;
+  }
+  if (cmd === 'uninstall') {
+    if (args.includes('--global')) { await uninstallGlobal(); return; }
+    console.log('Usage: dual-brain uninstall --global');
+    return;
+  }
   if (cmd === 'auth') {
     await cmdAuth(args.slice(1));
     return;
@@ -5651,6 +5997,7 @@ async function main() {
   if (cmd === 'think')    { await cmdThink(args.slice(1)); return; }
   if (cmd === 'review')   { await cmdReview(args.slice(1)); return; }
   if (cmd === 'ship')     { await cmdShip(); return; }
+  if (cmd === 'pr')       { await cmdPR(args.slice(1)); return; }
   if (cmd === 'status')   { await cmdStatus(args.slice(1)); return; }
   if (cmd === 'hot')      { cmdHot(args[1]); return; }
   if (cmd === 'cool')     { cmdCool(args[1]); return; }
@@ -5715,7 +6062,7 @@ fi
   // If cmd is not a recognized subcommand, treat the entire arg list as a task.
   // e.g. `dual-brain fix failing tests` → same as `dual-brain go "fix failing tests"`
   const KNOWN_COMMANDS = new Set([
-    'init', 'install', 'auth', 'go', 'do', 'plan', 'ship', 'think', 'review', 'status', 'hot', 'cool',
+    'init', 'install', 'uninstall', 'auth', 'go', 'do', 'plan', 'ship', 'think', 'review', 'pr', 'status', 'hot', 'cool',
     'remember', 'forget', 'break-glass', 'specialists', 'search', 'shell-hook', 'watch',
     '--help', '-h', '--version', '-v',
     ...Object.keys(loadSpecialistRegistry()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -23,7 +23,11 @@
     "./calibration": "./src/calibration.mjs",
     "./models": "./src/models.mjs",
     "./prompt-intel": "./src/prompt-intel.mjs",
-    "./replit": "./src/replit.mjs"
+    "./replit": "./src/replit.mjs",
+    "./continuity": "./src/continuity.mjs",
+    "./checkpoint": "./src/checkpoint.mjs",
+    "./pr-agent": "./src/pr-agent.mjs",
+    "./ci-triage": "./src/ci-triage.mjs"
   },
   "keywords": [
     "claude-code",
@@ -86,6 +90,10 @@
     "src/prompt-intel.mjs",
     "src/replit.mjs",
     "src/fx.mjs",
+    "src/continuity.mjs",
+    "src/checkpoint.mjs",
+    "src/ci-triage.mjs",
+    "src/pr-agent.mjs",
     "bin/*.mjs",
     "hooks/enforce-tier.mjs",
     "hooks/cost-logger.mjs",

package/src/awareness.mjs

@@ -358,3 +358,39 @@ export function invalidateCache() {
   _cache = null;
   _cacheTime = 0;
 }
+
+// ─── Ambiguity Detection ──────────────────────────────────────────────────────
+
+const TECHNICAL_TERMS = /\b(fix|bug|error|test|deploy|refactor|import|export|function|class|module|api|endpoint|auth|token|database|query|schema|migration|build|lint|type|interface|component|route|handler|middleware|config|env|secret|key|file|path|directory|repo|branch|commit|merge|pull|push|install|upgrade|package|dependency|version|release|publish|log|trace|debug|stack|exception|undefined|null|async|await|promise|fetch|request|response|status|server|client|socket|cache|session)\b/i;
+
+/**
+ * Detect whether a prompt is ambiguous and needs clarification before dispatch.
+ *
+ * A prompt is considered ambiguous when ALL of the following are true:
+ *   1. It is very short (under 4 words)
+ *   2. No file context is provided
+ *   3. It lacks specific technical terms that narrow the intent
+ *
+ * @param {string} prompt — the user's raw prompt
+ * @param {{ files?: string[] }} [context] — optional context (e.g. file paths)
+ * @returns {{ isAmbiguous: boolean, reason: string|null }}
+ */
+export function detectAmbiguity(prompt, context = {}) {
+  if (!prompt || typeof prompt !== 'string') {
+    return { isAmbiguous: true, reason: 'missing context: empty prompt' };
+  }
+
+  const words = prompt.trim().split(/\s+/).filter(Boolean);
+  const isTooShort = words.length < 4;
+  const hasFileContext = Array.isArray(context?.files) && context.files.length > 0;
+  const hasTechnicalTerms = TECHNICAL_TERMS.test(prompt);
+
+  if (isTooShort && !hasFileContext && !hasTechnicalTerms) {
+    return {
+      isAmbiguous: true,
+      reason: `unclear: prompt is vague ("${prompt.trim()}") — missing context about what to change and where`,
+    };
+  }
+
+  return { isAmbiguous: false, reason: null };
+}

package/src/checkpoint.mjs

@@ -0,0 +1,109 @@
+// checkpoint.mjs — Checkpoint wrapper for dual-brain execution safety.
+// Wraps Replit's native checkpoint system with a git-based fallback.
+// Exports: hasCheckpoints, createCheckpoint, listCheckpoints, getLastCheckpoint
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+/**
+ * Check if checkpoint capability is available.
+ * @returns {boolean}
+ */
+export function hasCheckpoints() {
+  try {
+    // Check for Replit checkpoint binary
+    if (existsSync('/usr/local/bin/replit-checkpoint')) return true;
+    execSync('which replit-checkpoint', { stdio: 'pipe', timeout: 2000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a checkpoint before a risky operation.
+ * @param {string} label — human-readable label like "before auth refactor"
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @returns {{ success: boolean, id: string|null, label: string, timestamp: string }}
+ */
+export function createCheckpoint(label, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const timestamp = new Date().toISOString();
+  const id = `cp-${Date.now()}`;
+
+  // Try Replit checkpoint first
+  if (hasCheckpoints()) {
+    try {
+      execSync('replit-checkpoint create', { cwd, stdio: 'pipe', timeout: 10000 });
+      _logCheckpoint({ id, label, timestamp, type: 'replit', status: 'created' }, cwd);
+      return { success: true, id, label, timestamp };
+    } catch {
+      // Fall through to git-based checkpoint
+    }
+  }
+
+  // Fallback: git stash + tag
+  try {
+    // Stash any uncommitted changes
+    const status = execSync('git status --porcelain', { cwd, encoding: 'utf8', timeout: 5000 }).trim();
+    if (status) {
+      execSync(`git stash push -m "dual-brain-checkpoint: ${label}"`, { cwd, stdio: 'pipe', timeout: 10000 });
+      execSync('git stash pop', { cwd, stdio: 'pipe', timeout: 10000 });
+    }
+    // Create a lightweight tag
+    const safeLabel = label.replace(/[^a-zA-Z0-9-_]/g, '-').slice(0, 50);
+    const tagName = `db-checkpoint/${safeLabel}-${Date.now()}`;
+    execSync(`git tag "${tagName}"`, { cwd, stdio: 'pipe', timeout: 5000 });
+    _logCheckpoint({ id, label, timestamp, type: 'git-tag', tag: tagName, status: 'created' }, cwd);
+    return { success: true, id, label, timestamp };
+  } catch {
+    _logCheckpoint({ id, label, timestamp, type: 'failed', status: 'failed' }, cwd);
+    return { success: false, id: null, label, timestamp };
+  }
+}
+
+/**
+ * List recent checkpoints (most recent first, up to 20).
+ * @param {string} [cwd]
+ * @returns {object[]}
+ */
+export function listCheckpoints(cwd) {
+  const logPath = join(cwd || process.cwd(), '.dual-brain', 'checkpoints.jsonl');
+  if (!existsSync(logPath)) return [];
+  try {
+    return readFileSync(logPath, 'utf8')
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map(line => JSON.parse(line))
+      .reverse()
+      .slice(0, 20);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get the most recent checkpoint.
+ * @param {string} [cwd]
+ * @returns {object|null}
+ */
+export function getLastCheckpoint(cwd) {
+  const checkpoints = listCheckpoints(cwd);
+  return checkpoints[0] || null;
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function _logCheckpoint(entry, cwd) {
+  const dir = join(cwd || process.cwd(), '.dual-brain');
+  mkdirSync(dir, { recursive: true });
+  const logPath = join(dir, 'checkpoints.jsonl');
+  const line = JSON.stringify(entry) + '\n';
+  try {
+    const existing = existsSync(logPath) ? readFileSync(logPath, 'utf8') : '';
+    writeFileSync(logPath, existing + line);
+  } catch {}
+}