total-recall-brain 3.1.0

package/src/cli/status.mjs

@@ -0,0 +1,296 @@
+/**
+ * total-recall status
+ *
+ * Show brain connection status, last sync time, local vs. remote vault hash
+ * comparison, and stale rule count.
+ *
+ * Usage:
+ *   npx total-recall status [options]
+ *
+ * Options:
+ *   --json             Emit machine-readable JSON
+ *   --brain <url>      Override the configured brain URL
+ *   --token <token>    Bearer PAT for the brain (overrides config / env)
+ *   --help, -h         Show this help
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { loadQueue } from '../core/research-queue.mjs';
+
+import { agentDir, brainDir, totalRecallToken } from '../core/config.mjs';
+
+const AGENT_DIR = agentDir;
+const BRAIN_CONFIG = path.join(brainDir, 'config', 'brain.json');
+const SYNC_STATE = path.join(brainDir, 'config', 'sync-state.json');
+const CLIENTS_REGISTRY = path.join(brainDir, 'config', 'clients.json');
+const INSTRUCTIONS_FILE = path.join(AGENT_DIR, 'INSTRUCTIONS.md');
+
+function parseArgs(args) {
+  const opts = { json: false, brain: null, token: null, help: false };
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--json': opts.json = true; break;
+      case '--brain': opts.brain = args[++i]; break;
+      case '--token': opts.token = args[++i]; break;
+      case '--help': case '-h': opts.help = true; break;
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+  total-recall status — Show brain connection and sync state
+
+  Usage: total-recall status [options]
+
+  Options:
+    --json             Emit machine-readable JSON
+    --brain <url>      Override the configured brain URL
+    --token <token>    Bearer PAT for the brain (overrides config / env)
+    --help, -h         Show this help
+`);
+}
+
+function loadBrainConfig() {
+  if (!fs.existsSync(BRAIN_CONFIG)) return null;
+  try { return JSON.parse(fs.readFileSync(BRAIN_CONFIG, 'utf8')); }
+  catch { return null; }
+}
+
+function loadSyncState() {
+  if (!fs.existsSync(SYNC_STATE)) return {};
+  try { return JSON.parse(fs.readFileSync(SYNC_STATE, 'utf8')); }
+  catch { return {}; }
+}
+
+function loadClientsRegistry() {
+  if (!fs.existsSync(CLIENTS_REGISTRY)) return {};
+  try { return JSON.parse(fs.readFileSync(CLIENTS_REGISTRY, 'utf8'))?.clients || {}; }
+  catch { return {}; }
+}
+
+function projectionsStatus(clients, instructionsMtime) {
+  return Object.entries(clients).map(([name, info]) => {
+    let fresh = null;
+    if (info.projectionPath && instructionsMtime) {
+      try {
+        const projMtime = fs.statSync(info.projectionPath).mtimeMs;
+        fresh = projMtime >= instructionsMtime;
+      } catch { fresh = false; }
+    }
+    return { name, label: info.label, mode: info.mode, connectedAt: info.connectedAt, projectionPath: info.projectionPath, fresh };
+  });
+}
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+async function probeBrain(brainUrl, token) {
+  const headers = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const out = { reachable: false, instructions_sha256: null, instructions_bytes: null, error: null };
+  try {
+    const res = await fetch(`${brainUrl.replace(/\/$/, '')}/api/instructions`, { headers });
+    if (!res.ok) {
+      out.error = `HTTP ${res.status}`;
+      return out;
+    }
+    const body = await res.json();
+    out.reachable = true;
+    out.instructions_sha256 = body.sha256 || null;
+    out.instructions_bytes = body.bytes || null;
+    out.modified = body.modified || null;
+  } catch (err) {
+    out.error = err.message;
+  }
+  return out;
+}
+
+export default async function statusCmd(args) {
+  const opts = parseArgs(args);
+  if (opts.help) { printHelp(); return; }
+
+  const brainConfig = loadBrainConfig();
+  const syncState = loadSyncState();
+  const clientsRegistry = loadClientsRegistry();
+  const brainUrl = opts.brain || brainConfig?.url || null;
+  const token = opts.token || brainConfig?.token || totalRecallToken || null;
+
+  const wizardConfigPath = path.join(brainDir, 'config', 'wizard-config.json');
+  let deployMode = 'unknown';
+  let dashboardUrl = null;
+  let tunnelPid = null;
+  let tunnelAlive = false;
+
+  if (fs.existsSync(wizardConfigPath)) {
+    try {
+      const wizardCfg = JSON.parse(fs.readFileSync(wizardConfigPath, 'utf8'));
+      deployMode = wizardCfg['deploy-mode'] || 'local';
+      dashboardUrl = wizardCfg['cfg-dash-url'] || null;
+    } catch {}
+  }
+
+  const logsDir = path.join(brainDir, 'logs');
+  const cfPidPath = path.join(logsDir, 'cloudflared.pid');
+  if (fs.existsSync(cfPidPath)) {
+    try {
+      const pid = parseInt(fs.readFileSync(cfPidPath, 'utf8').trim(), 10);
+      if (pid) {
+        tunnelPid = pid;
+        process.kill(pid, 0);
+        tunnelAlive = true;
+      }
+    } catch {
+      tunnelAlive = false;
+    }
+  }
+
+  // Live server /health check
+  let serverHealth = 'offline';
+  let serverUptime = null;
+  try {
+    let healthPort = 3000;
+    try {
+      const { default: cfg } = await import('../core/config.mjs');
+      if (cfg.port) healthPort = cfg.port;
+    } catch {}
+    const res = await fetch(`http://localhost:${healthPort}/health`, { signal: AbortSignal.timeout(2000) });
+    if (res.ok) {
+      const hData = await res.json();
+      serverHealth = hData.status || 'healthy';
+      serverUptime = hData.uptime_seconds || null;
+    }
+  } catch {}
+
+  // Daemon status
+  let daemonStatus = 'unknown';
+  try {
+    const { getDaemonStatus } = await import('../core/daemon-control.mjs');
+    daemonStatus = getDaemonStatus();
+  } catch {}
+
+  let localInstructions = null;
+  if (fs.existsSync(INSTRUCTIONS_FILE)) {
+    const buf = fs.readFileSync(INSTRUCTIONS_FILE);
+    const stat = fs.statSync(INSTRUCTIONS_FILE);
+    localInstructions = {
+      path: INSTRUCTIONS_FILE,
+      sha256: sha256(buf),
+      bytes: stat.size,
+      modified: stat.mtime.toISOString()
+    };
+  }
+
+  let remote = null;
+  if (brainUrl) {
+    remote = await probeBrain(brainUrl, token);
+  }
+
+  const inSync = !!(localInstructions && remote?.instructions_sha256 &&
+    remote.instructions_sha256 === localInstructions.sha256);
+
+  const instructionsMtime = localInstructions
+    ? fs.statSync(INSTRUCTIONS_FILE).mtimeMs
+    : null;
+  const clientProjections = projectionsStatus(clientsRegistry, instructionsMtime);
+
+  const report = {
+    server: {
+      status: serverHealth,
+      uptime_seconds: serverUptime
+    },
+    deploy: {
+      mode: deployMode,
+      dashboard_url: dashboardUrl,
+      tunnel_pid: tunnelPid,
+      tunnel_alive: tunnelAlive
+    },
+    daemon: daemonStatus,
+    brain: {
+      url: brainUrl,
+      configured: !!brainConfig,
+      reachable: remote?.reachable || false,
+      error: remote?.error || null
+    },
+    instructions: {
+      local: localInstructions,
+      remote: remote ? {
+        sha256: remote.instructions_sha256,
+        bytes: remote.instructions_bytes,
+        modified: remote.modified
+      } : null,
+      in_sync: inSync
+    },
+    last_sync: syncState.last_sync || null,
+    targets: syncState.targets ? Object.keys(syncState.targets) : [],
+    clients: clientProjections,
+    research: []
+  };
+
+  // Load ongoing research agenda
+  let ongoingResearch = [];
+  try {
+    ongoingResearch = loadQueue().filter(item => item.status === 'in_progress' || item.status === 'pending');
+    report.research = ongoingResearch.map(item => ({
+      id: item.id,
+      topic: item.topic,
+      status: item.status,
+      research_phase: item.research_phase,
+      updated_at: item.updated_at
+    }));
+  } catch (err) {
+    // Ignore queue loading errors if not configured or file doesn't exist
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log('\n  Total Recall — Status\n');
+  console.log(`  Brain Server:     ${serverHealth === 'offline' ? '🔴 Offline' : `🟢 Online (${serverUptime ? `${Math.floor(serverUptime / 60)}m uptime` : 'healthy'})`}`);
+  console.log(`  Deploy Mode:      ${deployMode}`);
+  console.log(`  Dashboard UI:     ${dashboardUrl || '(not resolved)'}`);
+  console.log(`  Remote Brain:     ${report.brain.url || '(none)'}`);
+  console.log(`  Tunnel Process:   ${tunnelPid ? (tunnelAlive ? `🟢 Active (PID ${tunnelPid})` : '🔴 Stale PID file') : '⚪ Inactive'}`);
+  console.log(`  Daemon Status:    ${daemonStatus === 'running' ? '🟢 Running' : daemonStatus === 'dead' ? '🔴 Dead' : '⚪ Not Running'}`);
+  console.log(`  Reachable:        ${report.brain.reachable ? 'yes' : 'no'}${report.brain.error ? `  (${report.brain.error})` : ''}`);
+  console.log(`  Local INSTR.:     ${localInstructions ? `${localInstructions.bytes} bytes, sha=${localInstructions.sha256.slice(0, 12)}…` : '(not compiled)'}`);
+  if (remote?.instructions_sha256) {
+    console.log(`  Remote INSTR.:    ${remote.instructions_bytes} bytes, sha=${remote.instructions_sha256.slice(0, 12)}…`);
+  }
+  console.log(`  In sync:          ${inSync ? 'yes' : 'no'}`);
+  console.log(`  Last sync:        ${report.last_sync || 'never'}`);
+  console.log(`  Sync targets:     ${report.targets.length ? report.targets.join(', ') : '(none)'}`);
+
+  if (clientProjections.length) {
+    console.log('\n  Connected clients:');
+    for (const c of clientProjections) {
+      let freshnessTag = '';
+      if (c.mode === 'file' || c.mode === 'symlink') {
+        freshnessTag = c.fresh === null ? '  (no projection)' : c.fresh ? '  ✅ fresh' : '  ⚠️  stale — run: total-recall connect ' + c.name;
+      }
+      console.log(`    ${c.label.padEnd(18)} [${c.mode}]${freshnessTag}`);
+    }
+  } else {
+    console.log('  Connected clients: (none — run total-recall connect <client>)');
+  }
+
+  if (ongoingResearch.length) {
+    console.log('\n  Ongoing Autonomous Research:');
+    for (const item of ongoingResearch) {
+      const badge = item.status === 'in_progress' ? '\x1b[36m🧪 [IN PROGRESS]\x1b[0m' : '\x1b[33m⏳ [PENDING]\x1b[0m';
+      const phase = item.research_phase || 'acquisition';
+      console.log(`    ${badge} "${item.topic}"`);
+      console.log(`      Phase: \x1b[36m${phase}\x1b[0m | ID: ${item.id.slice(0, 8)}…`);
+    }
+  } else {
+    console.log('\n  Ongoing Autonomous Research: (none)');
+  }
+  console.log();
+}

package/src/cli/sync.mjs

@@ -0,0 +1,383 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import matter from 'gray-matter';
+import { protectIDEInstructions } from '../core/protect-instructions.mjs';
+import { totalRecallToken } from '../core/config.mjs';
+
+const INJECTION_BEGIN = '<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->';
+const INJECTION_END = '<!-- END INJECTED MEMORY -->';
+const SHIMS = [
+  '.cursorrules',
+  'CLAUDE.md',
+  '.clauderules',
+  'AGENTS.md',
+  'GEMINI.md',
+  '.github/copilot-instructions.md',
+  '.vscode/copilot-instructions.md'
+];
+
+function parseArgs(args) {
+  const opts = {
+    brain: null,
+    token: null,
+    watch: false,
+    push: false,
+    intervalSeconds: 60,
+    help: false
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--brain': opts.brain = args[++i]; break;
+      case '--token': opts.token = args[++i]; break;
+      case '--watch': opts.watch = true; break;
+      case '--push': opts.push = true; break;
+      case '--interval': opts.intervalSeconds = Number(args[++i]) || 60; break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+    }
+  }
+
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+  total-recall sync — Sync brain instructions and back up vault to GitHub
+ 
+  Usage: total-recall sync [options]
+ 
+  Options:
+    --brain <url>       Brain base URL. Defaults to .agent/config/brain.json
+    --token <token>     Bearer PAT. Defaults to brain.json or TOTAL_RECALL_TOKEN
+    --watch             Keep syncing on an interval
+    --interval <sec>    Watch interval in seconds (default: 60)
+    --push              Back up vault to your GitHub fork (git add -f + push)
+    --help, -h          Show this help
+ 
+  Backup workflow (--push):
+    Commits .agent/skills/total-recall/memory-vault/, INSTRUCTIONS.md,
+    .agent/skills/total-recall/config/brain.json, and encrypted credentials (.agent/skills/total-recall/config/secrets.enc)
+    to your private fork via force-add (bypasses .gitignore) to ensure seamless portability across machines.
+    Run 'npx total-recall setup' to configure your GitHub fork first.
+`);
+}
+
+function workspaceAgentDir(cwd = process.cwd()) {
+  return path.join(cwd, '.agent');
+}
+
+function workspaceBrainDir(cwd = process.cwd()) {
+  return path.join(cwd, '.agent', 'skills', 'total-recall');
+}
+
+function loadBrainConfig(agentDir) {
+  const local = path.join(agentDir, 'skills', 'total-recall', 'config', 'brain.json');
+  const global = path.join(os.homedir(), '.agent', 'skills', 'total-recall', 'config', 'brain.json');
+  for (const file of [local, global]) {
+    if (!fs.existsSync(file)) continue;
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch { return null; }
+  }
+  return null;
+}
+
+function extractManagedBlock(content) {
+  const start = content.indexOf(INJECTION_BEGIN);
+  const end = content.indexOf(INJECTION_END);
+  if (start === -1 || end === -1 || end < start) return content.trim();
+  return content.slice(start, end + INJECTION_END.length).trim();
+}
+
+function replaceManagedBlock(existing, block) {
+  const start = existing.indexOf(INJECTION_BEGIN);
+  const end = existing.indexOf(INJECTION_END);
+  if (start === -1 || end === -1 || end < start) {
+    return `${existing.trimEnd()}\n\n${block}\n`;
+  }
+  return `${existing.slice(0, start)}${block}${existing.slice(end + INJECTION_END.length)}`;
+}
+
+function writeProjection(cwd, instructions) {
+  const instructionsFile = path.join(cwd, 'INSTRUCTIONS.md');
+  fs.writeFileSync(instructionsFile, instructions.endsWith('\n') ? instructions : `${instructions}\n`, 'utf8');
+
+  const block = extractManagedBlock(instructions);
+  const targets = {};
+  for (const shim of SHIMS) {
+    const target = path.join(cwd, shim);
+    const targetDir = path.dirname(target);
+    try {
+      if (fs.existsSync(target)) {
+        const stat = fs.lstatSync(target);
+        if (!stat.isSymbolicLink()) {
+          const existing = fs.readFileSync(target, 'utf8');
+          fs.writeFileSync(target, replaceManagedBlock(existing, block), 'utf8');
+          targets[shim] = 'updated';
+        } else {
+          targets[shim] = 'symlink';
+        }
+      } else {
+        // Ensure parent directory of the shim exists before writing/symlinking
+        if (!fs.existsSync(targetDir)) {
+          fs.mkdirSync(targetDir, { recursive: true });
+        }
+        // Use relative path target for symlink so it's correct from the subdirectory
+        const relativeTarget = path.relative(targetDir, instructionsFile);
+        fs.symlinkSync(relativeTarget, target);
+        targets[shim] = 'symlinked';
+      }
+    } catch (err) {
+      targets[shim] = `skipped: ${err.message}`;
+    }
+  }
+
+  return { instructionsFile, targets };
+}
+
+function writeSyncState(agentDir, state) {
+  const configDir = path.join(agentDir, 'skills', 'total-recall', 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+  const stateFile = path.join(configDir, 'sync-state.json');
+  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+  return stateFile;
+}
+
+async function pullInstructions(brainUrl, token) {
+  const headers = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetch(`${brainUrl.replace(/\/$/, '')}/api/instructions`, { headers });
+  if (!res.ok) {
+    throw new Error(`Failed to pull instructions: HTTP ${res.status}`);
+  }
+  return res.json();
+}
+
+async function runOnce(opts) {
+  const cwd = process.cwd();
+  const agentDir = workspaceAgentDir(cwd);
+  const brainConfig = loadBrainConfig(agentDir);
+  const brainUrl = opts.brain || brainConfig?.url;
+  const token = opts.token || brainConfig?.token || totalRecallToken;
+
+  if (!brainUrl) {
+    throw new Error('No brain URL configured. Pass --brain <url> or create .agent/config/brain.json.');
+  }
+
+  // Auto-protect manual IDE edits locally and sync them to the brain first
+  const vaultDir = path.join(workspaceBrainDir(cwd), 'memory-vault');
+  const derivedDir = path.join(workspaceBrainDir(cwd), 'memory-derived');
+  const instructionsFile = path.join(cwd, 'INSTRUCTIONS.md');
+
+  // Ensure local directories exist so we can track and protect direct IDE manual edits
+  fs.mkdirSync(vaultDir, { recursive: true });
+  fs.mkdirSync(derivedDir, { recursive: true });
+
+  try {
+    const result = protectIDEInstructions({ vaultDir, derivedDir, instructionsFile });
+    if (result && result.imported > 0) {
+      console.error(`  🛡️  [total-recall] Auto-captured ${result.imported} manual IDE instruction edit(s) locally.`);
+      
+      const headers = { 'Content-Type': 'application/json' };
+      if (token) headers.Authorization = `Bearer ${token}`;
+
+      for (const slug of result.slugs) {
+        const nodeFile = path.join(vaultDir, 'invariants', `${slug}.md`);
+        if (!fs.existsSync(nodeFile)) continue;
+
+        const raw = fs.readFileSync(nodeFile, 'utf8');
+        const { data, content } = matter(raw);
+
+        const payload = {
+          slug: data.slug,
+          title: data.title,
+          category: data.category,
+          content: content.trim(),
+          tags: data.tags,
+          priority: data.priority,
+          modality: data.modality,
+          confidence: data.confidence,
+          importance: data.importance,
+          status: data.status,
+          created: data.created,
+          updated: data.updated
+        };
+
+        console.error(`  🛡️  Pushing new invariant to remote brain: ${slug}...`);
+        const postRes = await fetch(`${brainUrl.replace(/\/$/, '')}/api/memory`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(payload)
+        });
+
+        if (!postRes.ok) {
+          if (postRes.status === 409) {
+            console.error(`  ℹ️  Invariant already exists on brain, updating: ${slug}...`);
+            const putRes = await fetch(`${brainUrl.replace(/\/$/, '')}/api/memory/${slug}`, {
+              method: 'PUT',
+              headers,
+              body: JSON.stringify(payload)
+            });
+            if (!putRes.ok) {
+              console.error(`  ⚠️  Failed to update invariant on brain: HTTP ${putRes.status}`);
+            }
+          } else {
+            console.error(`  ⚠️  Failed to push invariant to brain: HTTP ${postRes.status}`);
+          }
+        }
+      }
+
+      // Trigger remote recompile so the pulled instructions contain the new changes
+      console.error(`  ⚙️  Triggering remote recompile on brain...`);
+      const compileHeaders = {};
+      if (token) compileHeaders.Authorization = `Bearer ${token}`;
+      const compileRes = await fetch(`${brainUrl.replace(/\/$/, '')}/api/vault/compile`, {
+        method: 'POST',
+        headers: compileHeaders
+      });
+
+      if (!compileRes.ok) {
+        console.error(`  ⚠️  Failed to trigger remote compile: HTTP ${compileRes.status}`);
+      } else {
+        console.error(`  ✅  Remote compile triggered successfully.`);
+      }
+    }
+  } catch (err) {
+    console.error(`  ⚠️  [total-recall] Failed to run local instruction protection: ${err.message}`);
+  }
+
+  const remote = await pullInstructions(brainUrl, token);
+  if (!remote.content) {
+    throw new Error('Remote /api/instructions response did not include content.');
+  }
+
+  const projection = writeProjection(cwd, remote.content);
+
+  // Save pristine system compiled output locally for IDE edit diffing in subsequent sync cycles
+  try {
+    const backupFile = path.join(derivedDir, 'INSTRUCTIONS.system.md');
+    fs.writeFileSync(backupFile, remote.content, 'utf8');
+  } catch (err) {
+    // Non-fatal
+  }
+  const stateFile = writeSyncState(agentDir, {
+    last_sync: new Date().toISOString(),
+    brain_url: brainUrl,
+    remote: {
+      sha256: remote.sha256 || null,
+      bytes: remote.bytes || null,
+      modified: remote.modified || null
+    },
+    targets: projection.targets
+  });
+
+  return {
+    brain_url: brainUrl,
+    instructions_file: projection.instructionsFile,
+    sync_state_file: stateFile,
+    remote_sha256: remote.sha256 || null,
+    targets: projection.targets
+  };
+}
+
+// ─── GitHub fork backup ──────────────────────────────────────────────────────
+
+// Paths to force-add to the fork (bypasses .gitignore).
+// Encrypted secrets.enc are force-committed to enable seamless portability.
+const VAULT_FORCE_ADD = [
+  '.agent/skills/total-recall/memory-vault',
+  'INSTRUCTIONS.md',
+  '.agent/skills/total-recall/config/brain.json',
+  '.agent/skills/total-recall/config/secrets.enc',
+  '.agent/secrets.enc',
+];
+
+function gitRun(args, opts = {}) {
+  const result = spawnSync('git', args, {
+    stdio: opts.silent ? 'pipe' : 'inherit',
+    encoding: 'utf8',
+  });
+  if (result.status !== 0 && !opts.ignoreErrors) {
+    throw new Error(`git ${args[0]} failed: ${(result.stderr || '').trim()}`);
+  }
+  return (result.stdout || '').trim();
+}
+
+function pushToFork() {
+  // Verify we're in a git repo
+  const root = gitRun(['rev-parse', '--show-toplevel'], { silent: true, ignoreErrors: true });
+  if (!root) throw new Error('Not inside a git repository.');
+
+  // Warn if origin appears to be the upstream (not a personal fork)
+  const originUrl = gitRun(['remote', 'get-url', 'origin'], { silent: true, ignoreErrors: true });
+  if (originUrl.includes('gregiteen/total-recall')) {
+    console.error('  ⚠️  origin is the upstream repo, not your personal fork.');
+    console.error('  Set up your fork first:');
+    console.error('    git remote rename origin upstream');
+    console.error('    git remote add origin https://github.com/YOUR_USERNAME/total-recall.git');
+    throw new Error('Configure your fork as origin before using sync --push.');
+  }
+
+  // Force-add vault files (bypasses .gitignore)
+  for (const target of VAULT_FORCE_ADD) {
+    if (fs.existsSync(path.join(root, target))) {
+      gitRun(['add', '-f', target], { ignoreErrors: true });
+    }
+  }
+
+  // Nothing staged? Already up to date.
+  const status = gitRun(['status', '--porcelain'], { silent: true });
+  if (!status) {
+    console.error('  ℹ  Vault is already up to date with origin — nothing to push.');
+    return { committed: false };
+  }
+
+  const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+  gitRun(['commit', '-m', `vault: backup ${timestamp}`]);
+  gitRun(['push', 'origin', 'main']);
+  console.error(`  ✅ Vault backed up to origin at ${timestamp}`);
+
+  return { committed: true, timestamp };
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+export default async function sync(args) {
+  const opts = parseArgs(args);
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  // --push mode: back up vault to GitHub fork
+  if (opts.push) {
+    pushToFork();
+    return;
+  }
+
+  async function tick() {
+    const result = await runOnce(opts);
+    console.error(`  Synced ${result.instructions_file}`);
+    console.error(`  Remote sha: ${result.remote_sha256 || 'unknown'}`);
+    return result;
+  }
+
+  await tick();
+  if (!opts.watch) return;
+
+  const intervalMs = Math.max(5, opts.intervalSeconds) * 1000;
+  console.error(`  Watching every ${Math.round(intervalMs / 1000)}s. Press Ctrl+C to stop.`);
+  await new Promise((resolve) => {
+    const timer = setInterval(() => {
+      tick().catch(err => console.error(`  Sync failed: ${err.message}`));
+    }, intervalMs);
+    process.on('SIGINT', () => {
+      clearInterval(timer);
+      resolve();
+    });
+  });
+}