total-recall-brain 3.18.0 → 3.18.2

package/bin/total-recall.mjs

@@ -51,6 +51,7 @@ const COMMANDS = {
   daemon:   'daemon.mjs',
   restore:  'restore.mjs',
   upgrade:  'upgrade.mjs',
+  update:   'update.mjs',
   friction: 'friction.mjs',
   chat:     'chat.mjs',
   status:   'status.mjs',
@@ -109,6 +110,7 @@ function printHelp() {
     status / doctor     Health and diagnostics
 
   Optional:
+    update [--apply]    Auto-download total-recall-brain for registered repos
     research, share, ingest, import, export, relay, setup, deploy,
     start, backup, restore, config, map, generate-pat, lint, sync, …
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.18.0",
+  "version": "3.18.2",
   "description": "Personal AI system — database-free, SSSS-powered intelligence engine deployable to any POSIX host.",
   "type": "module",
   "workspaces": [

package/src/cli/update.mjs

@@ -0,0 +1,115 @@
+/**
+ * total-recall update — check / install total-recall-brain on registered projects.
+ *
+ * Usage:
+ *   npx total-recall update              # check only
+ *   npx total-recall update --apply      # install latest where needed
+ *   npx total-recall update --apply --force
+ *   npx total-recall update --repo /path/to/app
+ */
+
+import {
+  runPackageAutoUpdate,
+  fetchLatestNpmVersion,
+  isPackageAutoUpdateEnabled,
+  PACKAGE_NAME,
+} from '../core/package-auto-update.mjs';
+import { brainDir } from '../core/config.mjs';
+
+function parseArgs(args) {
+  const opts = {
+    apply: false,
+    force: false,
+    dryRun: false,
+    help: false,
+    repos: [],
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--apply' || a === '--install') opts.apply = true;
+    else if (a === '--force') opts.force = true;
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--repo' && args[i + 1]) opts.repos.push(args[++i]);
+  }
+  return opts;
+}
+
+function printHelp() {
+  console.log(`
+  total-recall update — Auto-download ${PACKAGE_NAME} for registered projects
+
+  Roots: project-registry + TR_SYNC_REPOS + --repo (never hardcodes product paths)
+
+  Usage:
+    total-recall update                 Report status (dry)
+    total-recall update --apply         npm install latest where behind
+    total-recall update --apply --force Ignore throttle / disabled flag
+    total-recall update --repo <path>   Include extra root (repeatable)
+
+  Env:
+    TR_AUTO_UPDATE_PACKAGE=0   Disable daemon cron auto-update (default: on)
+    TR_SYNC_REPOS=/a:/b       Extra project roots
+
+  Source monorepos named ${PACKAGE_NAME} are skipped (use git, not npm into self).
+`);
+}
+
+export default async function update(args = []) {
+  const opts = parseArgs(args);
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  const latest = fetchLatestNpmVersion();
+  console.log(`\n  Package: ${PACKAGE_NAME}`);
+  console.log(`  Latest on npm: ${latest || '(unavailable)'}`);
+  console.log(`  Auto-update (daemon): ${isPackageAutoUpdateEnabled() ? 'enabled' : 'disabled'}`);
+
+  const dryRun = !opts.apply || opts.dryRun;
+  const summary = await runPackageAutoUpdate({
+    brainDir,
+    roots: opts.repos.length ? opts.repos : undefined,
+    dryRun,
+    force: opts.force || opts.apply,
+    skipThrottle: opts.apply || opts.force,
+    save: true,
+  });
+
+  if (summary.skipped) {
+    console.log(`\n  Skipped: ${summary.reason}`);
+    if (summary.next_check_in_ms) {
+      console.log(`  Next check in ~${Math.ceil(summary.next_check_in_ms / 60000)} min`);
+    }
+  }
+
+  const results = summary.results || [];
+  if (!results.length) {
+    console.log('\n  No project roots found. Track repos with:');
+    console.log('    npx total-recall skill track /path/to/repo');
+    console.log('    # or set TR_SYNC_REPOS\n');
+    return;
+  }
+
+  console.log(`\n  Projects (${results.length}):`);
+  for (const r of results) {
+    const inst = r.installed || '—';
+    const mark =
+      r.status === 'updated' || r.status === 'would_update'
+        ? '↑'
+        : r.status === 'up_to_date'
+          ? '✓'
+          : r.status === 'failed'
+            ? '✗'
+            : '·';
+    console.log(`    ${mark} ${r.name}: ${inst} → ${r.latest || latest}  [${r.status}]`);
+    if (r.error) console.log(`        error: ${r.error}`);
+  }
+
+  if (dryRun && results.some((r) => r.status === 'would_update')) {
+    console.log('\n  Run with --apply to install updates.\n');
+  } else {
+    console.log('');
+  }
+}

package/src/core/crons.mjs

@@ -2,6 +2,7 @@ import { logger } from './logger.mjs';
 import { runGitHubSync, getGitHubSyncStatus } from './github-sync.mjs';
 import { watchObsidianDirectory } from './obsidian-sync.mjs';
 import { getSecret } from './secrets-store.mjs';
+import { runPackageAutoUpdate } from './package-auto-update.mjs';
 
 /**
  * runCrons — scheduled background jobs.
@@ -27,6 +28,19 @@ export async function runCrons(options) {
     } catch {
       // Obsidian not configured
     }
+
+    // 3. npm package auto-update for registered projects (total-recall-brain)
+    try {
+      const pkg = await runPackageAutoUpdate({ brainDir });
+      if (!pkg.skipped && (pkg.updated > 0 || pkg.failed > 0)) {
+        logger.info({
+          subsystem: 'cron',
+          message: `package-auto-update: latest=${pkg.latest} updated=${pkg.updated} failed=${pkg.failed}`,
+        });
+      }
+    } catch (err) {
+      logger.warn({ subsystem: 'cron', message: `package-auto-update failed: ${err.message}` });
+    }
   } catch (err) {
     logger.error({ subsystem: 'cron', message: `Cron execution failed: ${err.message}` });
   }

package/src/core/daemon-loop.mjs

@@ -239,6 +239,20 @@ async function main() {
     logger.info({ subsystem: 'daemon-loop', message: `Mesh node patch failed: ${err.message}` });
   }
 
+  // npm total-recall-brain auto-update for registered projects (throttled thereafter via crons)
+  try {
+    const { runPackageAutoUpdate } = await import('./package-auto-update.mjs');
+    const pkg = await runPackageAutoUpdate({ brainDir: BRAIN_DIR, skipThrottle: true });
+    if (!pkg.skipped) {
+      logger.info({
+        subsystem: 'daemon-loop',
+        message: `Boot package-auto-update: latest=${pkg.latest} updated=${pkg.updated || 0} failed=${pkg.failed || 0}`,
+      });
+    }
+  } catch (err) {
+    logger.info({ subsystem: 'daemon-loop', message: `Boot package-auto-update failed: ${err.message}` });
+  }
+
   // Deterministic election (lowest mesh IP) — tryAcquire/renew are no-op shims
   // that re-evaluate isLeader(); no node-local lease documents are written.
   const { tryAcquireLease, isLeader, getLeaderInfo, renewLease } = await import('./leader-election.mjs');

package/src/core/embeddings.mjs

@@ -15,20 +15,56 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { throttledFetch } from './throttled-fetch.mjs';
 import Database from 'better-sqlite3';
-import * as sqliteVss from 'sqlite-vss';
+import {
+  getVectorLoadablePath,
+  getVssLoadablePath,
+} from 'sqlite-vss';
 
 import { googleApiKey, embedModel, brainDir as defaultBrainDir } from './config.mjs';
 import { logger } from './logger.mjs';
 
 const DEFAULT_EMBED_MODEL = embedModel;
-const GOOGLE_API_KEY = googleApiKey || process.env.GOOGLE_API_KEY;
-const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+
+/** Resolve API keys at call time so tests can set env after import. */
+function resolveGoogleApiKey() {
+  return googleApiKey || process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY || null;
+}
+
+function resolveOpenAiApiKey() {
+  return process.env.OPENAI_API_KEY || null;
+}
 
 let dbInstance = null;
 let currentDbPath = null;
+/** @type {WeakMap<object, boolean>} */
+const dbVssEnabled = new WeakMap();
+
+/**
+ * better-sqlite3 on Linux appends ".so" when the path already ends in ".so",
+ * producing "vss0.so.so". Strip known extensions before loadExtension.
+ */
+function loadExtensionBare(db, absolutePath) {
+  const bare = String(absolutePath).replace(/\.(so|dylib|dll)$/i, '');
+  try {
+    db.loadExtension(bare);
+  } catch {
+    db.loadExtension(absolutePath);
+  }
+}
+
+function tryLoadSqliteVss(db) {
+  try {
+    loadExtensionBare(db, getVectorLoadablePath());
+    loadExtensionBare(db, getVssLoadablePath());
+    return true;
+  } catch (err) {
+    logger.warn('embeddings', `sqlite-vss unavailable; using JSON-only store: ${err.message}`);
+    return false;
+  }
+}
 
 /**
- * Get or initialize the SQLite database connection with sqlite-vss loaded.
+ * Get or initialize the SQLite database connection with sqlite-vss loaded when available.
  */
 function getDb(derivedDir) {
   const dbPath = path.join(derivedDir, 'embeddings.db');
@@ -43,9 +79,8 @@ function getDb(derivedDir) {
   fs.mkdirSync(derivedDir, { recursive: true });
   
   const db = new Database(dbPath);
-  
-  // Load sqlite-vss extension
-  sqliteVss.load(db);
+  const vssOk = tryLoadSqliteVss(db);
+  dbVssEnabled.set(db, vssOk);
 
   // Initialize schema
   db.exec(`
@@ -67,22 +102,58 @@ function getDb(derivedDir) {
       generated_at TEXT,
       embedding_json TEXT
     );
-    
-    -- Virtual tables for VSS
-    CREATE VIRTUAL TABLE IF NOT EXISTS vss_vault_embeddings USING vss0(
-      embedding(768)
-    );
-    
-    CREATE VIRTUAL TABLE IF NOT EXISTS vss_session_embeddings USING vss0(
-      embedding(768)
-    );
   `);
 
+  if (vssOk) {
+    db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS vss_vault_embeddings USING vss0(
+        embedding(768)
+      );
+      CREATE VIRTUAL TABLE IF NOT EXISTS vss_session_embeddings USING vss0(
+        embedding(768)
+      );
+    `);
+  }
+
   dbInstance = db;
   currentDbPath = dbPath;
   return db;
 }
 
+function hasVss(db) {
+  return dbVssEnabled.get(db) === true;
+}
+
+function vssReplaceVault(db, rowId, embeddingJson) {
+  if (!hasVss(db)) return;
+  db.prepare('DELETE FROM vss_vault_embeddings WHERE rowid = ?').run(rowId);
+  db.prepare('INSERT INTO vss_vault_embeddings(rowid, embedding) VALUES (?, ?)').run(rowId, embeddingJson);
+}
+
+function vssDeleteVault(db, rowId) {
+  if (!hasVss(db)) return;
+  db.prepare('DELETE FROM vss_vault_embeddings WHERE rowid = ?').run(rowId);
+}
+
+function vssReplaceSession(db, rowId, embeddingJson) {
+  if (!hasVss(db)) return;
+  db.prepare('DELETE FROM vss_session_embeddings WHERE rowid = ?').run(rowId);
+  db.prepare('INSERT INTO vss_session_embeddings(rowid, embedding) VALUES (?, ?)').run(rowId, embeddingJson);
+}
+
+function vssDeleteSession(db, rowId) {
+  if (!hasVss(db)) return;
+  db.prepare('DELETE FROM vss_session_embeddings WHERE rowid = ?').run(rowId);
+}
+
+function vssClearAll(db) {
+  if (!hasVss(db)) {
+    db.exec('DELETE FROM vault_embeddings; DELETE FROM session_embeddings;');
+    return;
+  }
+  db.exec('DELETE FROM vss_vault_embeddings; DELETE FROM vault_embeddings; DELETE FROM vss_session_embeddings; DELETE FROM session_embeddings;');
+}
+
 function sha256(text) {
   return crypto.createHash('sha256').update(text).digest('hex');
 }
@@ -94,12 +165,13 @@ async function resolveEmbeddingModel(selectedModel = embedModel) {
     return selectedModel;
   }
 
-  if (!GOOGLE_API_KEY) {
+  const googleKey = resolveGoogleApiKey();
+  if (!googleKey) {
     return 'gemini-embedding-2';
   }
 
   try {
-    const res = await throttledFetch(`https://generativelanguage.googleapis.com/v1beta/models?key=${GOOGLE_API_KEY}`, {
+    const res = await throttledFetch(`https://generativelanguage.googleapis.com/v1beta/models?key=${googleKey}`, {
       signal: AbortSignal.timeout(5000)
     });
     if (res.ok) {
@@ -124,12 +196,13 @@ async function resolveEmbeddingModel(selectedModel = embedModel) {
 }
 
 async function getGoogleEmbedding(text, model) {
-  if (!GOOGLE_API_KEY) {
+  const googleKey = resolveGoogleApiKey();
+  if (!googleKey) {
     throw new Error('GOOGLE_API_KEY not set. Cannot generate embeddings.');
   }
 
   const resolved = await resolveEmbeddingModel(model);
-  const url = `https://generativelanguage.googleapis.com/v1beta/models/${resolved}:embedContent?key=${GOOGLE_API_KEY}`;
+  const url = `https://generativelanguage.googleapis.com/v1beta/models/${resolved}:embedContent?key=${googleKey}`;
 
   const res = await throttledFetch(url, {
     method: 'POST',
@@ -155,7 +228,8 @@ async function getGoogleEmbedding(text, model) {
 }
 
 async function getOpenAIEmbedding(text, model = 'text-embedding-3-small') {
-  if (!OPENAI_API_KEY) {
+  const openaiKey = resolveOpenAiApiKey();
+  if (!openaiKey) {
     throw new Error('Neither GOOGLE_API_KEY nor OPENAI_API_KEY is set. Cannot generate embeddings.');
   }
 
@@ -163,7 +237,7 @@ async function getOpenAIEmbedding(text, model = 'text-embedding-3-small') {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
-      'Authorization': `Bearer ${OPENAI_API_KEY}`,
+      'Authorization': `Bearer ${openaiKey}`,
     },
     body: JSON.stringify({ model, input: text }),
     signal: AbortSignal.timeout(30000),
@@ -184,9 +258,11 @@ async function getOpenAIEmbedding(text, model = 'text-embedding-3-small') {
 
 export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
   const input = String(text).slice(0, 8000);
+  const googleKey = resolveGoogleApiKey();
+  const openaiKey = resolveOpenAiApiKey();
 
   let embedding;
-  if (GOOGLE_API_KEY) {
+  if (googleKey) {
     try {
       embedding = await getGoogleEmbedding(input, model);
     } catch (err) {
@@ -194,7 +270,7 @@ export async function getEmbedding(text, _unused, model = DEFAULT_EMBED_MODEL) {
     }
   }
 
-  if (!embedding && OPENAI_API_KEY) {
+  if (!embedding && openaiKey) {
     try {
       embedding = await getOpenAIEmbedding(input);
     } catch (err) {
@@ -254,10 +330,8 @@ export function saveEmbeddingToIndex(derivedDir, slug, embedding, model = DEFAUL
         embedding_json=excluded.embedding_json
     `).run(slug, model, now, embeddingJson);
     
-    // Add to vss index
     const rowId = db.prepare('SELECT rowid FROM vault_embeddings WHERE slug = ?').get(slug).rowid;
-    db.prepare('DELETE FROM vss_vault_embeddings WHERE rowid = ?').run(rowId);
-    db.prepare('INSERT INTO vss_vault_embeddings(rowid, embedding) VALUES (?, ?)').run(rowId, embeddingJson);
+    vssReplaceVault(db, rowId, embeddingJson);
   })();
 }
 
@@ -266,7 +340,7 @@ export function removeEmbeddingFromIndex(derivedDir, slug) {
   db.transaction(() => {
     const row = db.prepare('SELECT rowid FROM vault_embeddings WHERE slug = ?').get(slug);
     if (row) {
-      db.prepare('DELETE FROM vss_vault_embeddings WHERE rowid = ?').run(row.rowid);
+      vssDeleteVault(db, row.rowid);
       db.prepare('DELETE FROM vault_embeddings WHERE slug = ?').run(slug);
     }
   })();
@@ -295,7 +369,8 @@ export async function buildEmbeddingsIndex(nodes, derivedDir, opts = {}) {
   const db = getDb(derivedDir);
 
   if (force) {
-    db.exec('DELETE FROM vss_vault_embeddings; DELETE FROM vault_embeddings;');
+    if (hasVss(db)) db.exec('DELETE FROM vss_vault_embeddings;');
+    db.exec('DELETE FROM vault_embeddings;');
   }
 
   const existing = force ? {} : loadEmbeddingsIndex(derivedDir);
@@ -312,7 +387,7 @@ export async function buildEmbeddingsIndex(nodes, derivedDir, opts = {}) {
       for (const slug of toDelete) {
         const row = db.prepare('SELECT rowid FROM vault_embeddings WHERE slug = ?').get(slug);
         if (row) {
-          db.prepare('DELETE FROM vss_vault_embeddings WHERE rowid = ?').run(row.rowid);
+          vssDeleteVault(db, row.rowid);
           db.prepare('DELETE FROM vault_embeddings WHERE slug = ?').run(slug);
         }
       }
@@ -350,8 +425,7 @@ export async function buildEmbeddingsIndex(nodes, derivedDir, opts = {}) {
         `).run(node.slug, model, now, contentHash, embeddingJson);
         
         const rowId = db.prepare('SELECT rowid FROM vault_embeddings WHERE slug = ?').get(node.slug).rowid;
-        db.prepare('DELETE FROM vss_vault_embeddings WHERE rowid = ?').run(rowId);
-        db.prepare('INSERT INTO vss_vault_embeddings(rowid, embedding) VALUES (?, ?)').run(rowId, embeddingJson);
+        vssReplaceVault(db, rowId, embeddingJson);
       })();
 
       built++;
@@ -405,8 +479,7 @@ export function saveSessionEmbeddingToIndex(derivedDir, key, snippet, embedding,
     `).run(key, session_id, chunk, 1, snippet.slice(0, 300), model, now, embeddingJson);
     
     const rowId = db.prepare('SELECT rowid FROM session_embeddings WHERE key = ?').get(key).rowid;
-    db.prepare('DELETE FROM vss_session_embeddings WHERE rowid = ?').run(rowId);
-    db.prepare('INSERT INTO vss_session_embeddings(rowid, embedding) VALUES (?, ?)').run(rowId, embeddingJson);
+    vssReplaceSession(db, rowId, embeddingJson);
   })();
 }
 
@@ -415,7 +488,7 @@ export function removeSessionEmbeddingFromIndex(derivedDir, sessionId) {
   db.transaction(() => {
     const rows = db.prepare('SELECT rowid, key FROM session_embeddings WHERE session_id = ?').all(sessionId);
     for (const row of rows) {
-      db.prepare('DELETE FROM vss_session_embeddings WHERE rowid = ?').run(row.rowid);
+      vssDeleteSession(db, row.rowid);
       db.prepare('DELETE FROM session_embeddings WHERE key = ?').run(row.key);
     }
   })();
@@ -462,7 +535,8 @@ export async function buildSessionEmbeddingsIndex(sessionsDir, derivedDir, opts
   if (files.length === 0) return { indexed: 0, skipped: 0, failed: 0, chunks: 0 };
 
   if (force) {
-    db.exec('DELETE FROM vss_session_embeddings; DELETE FROM session_embeddings;');
+    if (hasVss(db)) db.exec('DELETE FROM vss_session_embeddings;');
+    db.exec('DELETE FROM session_embeddings;');
   }
 
   const existing = force ? {} : loadSessionEmbeddingsIndex(derivedDir);
@@ -497,8 +571,7 @@ export async function buildSessionEmbeddingsIndex(sessionsDir, derivedDir, opts
           `).run(key, sessionId, i, chunks.length, snippet, model, new Date().toISOString(), JSON.stringify(embedding));
           
           const rowId = db.prepare('SELECT rowid FROM session_embeddings WHERE key = ?').get(key).rowid;
-          db.prepare('DELETE FROM vss_session_embeddings WHERE rowid = ?').run(rowId);
-          db.prepare('INSERT INTO vss_session_embeddings(rowid, embedding) VALUES (?, ?)').run(rowId, JSON.stringify(embedding));
+          vssReplaceSession(db, rowId, JSON.stringify(embedding));
         })();
 
         totalChunks++;

package/src/core/package-auto-update.mjs

@@ -0,0 +1,401 @@
+/**
+ * Auto-download total-recall-brain updates into registered project roots.
+ *
+ * Roots come only from:
+ *   - global/project project-registry.json
+ *   - TR_SYNC_REPOS env (path separators : or ,)
+ *   - optional explicit roots[] (CLI / API)
+ *
+ * Never hardcodes product repo paths. Opt-out: TR_AUTO_UPDATE_PACKAGE=0
+ * Source monorepos (package name total-recall-brain with src/server) are skipped
+ * for npm install — they track git, not the published tarball.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { logger } from './logger.mjs';
+
+export const PACKAGE_NAME = 'total-recall-brain';
+export const DEFAULT_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000; // 6 hours
+
+/**
+ * @returns {boolean}
+ */
+export function isPackageAutoUpdateEnabled() {
+  const v = process.env.TR_AUTO_UPDATE_PACKAGE ?? process.env.TR_AUTO_UPDATE;
+  if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+  // Default on so consumer installs stay current once the daemon runs.
+  return true;
+}
+
+/**
+ * @param {string} [brainDir]
+ * @returns {string}
+ */
+export function packageUpdateStatePath(brainDir) {
+  const base = brainDir || path.join(os.homedir(), '.agent', 'skills', 'total-recall');
+  return path.join(base, 'memory-derived', 'package-auto-update.json');
+}
+
+/**
+ * @param {string} statePath
+ * @returns {{ last_check_at?: string, last_latest?: string, last_results?: object[] }}
+ */
+export function loadUpdateState(statePath) {
+  try {
+    if (!fs.existsSync(statePath)) return {};
+    return JSON.parse(fs.readFileSync(statePath, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * @param {string} statePath
+ * @param {object} state
+ */
+export function saveUpdateState(statePath, state) {
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+}
+
+/**
+ * Resolve registry JSON paths (global brain + optional brainDir config).
+ * @param {{ brainDir?: string }} [opts]
+ * @returns {string[]}
+ */
+export function resolveRegistryFiles(opts = {}) {
+  const files = [];
+  const globalReg = path.join(os.homedir(), '.agent', 'skills', 'total-recall', 'config', 'project-registry.json');
+  if (fs.existsSync(globalReg)) files.push(globalReg);
+  if (opts.brainDir) {
+    const local = path.join(opts.brainDir, 'config', 'project-registry.json');
+    if (fs.existsSync(local) && local !== globalReg) files.push(local);
+  }
+  return files;
+}
+
+/**
+ * @param {string} registryPath
+ * @returns {Array<{ name?: string, path?: string }>}
+ */
+export function readRegistryEntries(registryPath) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+    return Array.isArray(raw) ? raw : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @returns {string[]}
+ */
+export function rootsFromEnv() {
+  const raw = process.env.TR_SYNC_REPOS || '';
+  if (!raw.trim()) return [];
+  return raw
+    .split(/[:|,]/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((p) => path.resolve(p));
+}
+
+/**
+ * Unique absolute project roots from registry + env + explicit.
+ * @param {{ brainDir?: string, roots?: string[] }} [opts]
+ * @returns {Array<{ root: string, name: string, source: string }>}
+ */
+export function listUpdateRoots(opts = {}) {
+  const byRoot = new Map();
+
+  function add(root, name, source) {
+    if (!root || typeof root !== 'string') return;
+    const abs = path.resolve(root);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return;
+    if (!byRoot.has(abs)) {
+      byRoot.set(abs, { root: abs, name: name || path.basename(abs), source });
+    }
+  }
+
+  for (const file of resolveRegistryFiles(opts)) {
+    for (const entry of readRegistryEntries(file)) {
+      add(entry.path, entry.name, 'project-registry');
+    }
+  }
+  for (const r of rootsFromEnv()) {
+    add(r, path.basename(r), 'TR_SYNC_REPOS');
+  }
+  for (const r of opts.roots || []) {
+    add(r, path.basename(path.resolve(r)), 'explicit');
+  }
+
+  return [...byRoot.values()];
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {string|null}
+ */
+export function readPackageJsonVersionField(projectRoot, field = 'version') {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg?.[field] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ declared: string|null, installed: string|null, isSourceTree: boolean, packageName: string|null }}
+ */
+export function inspectProjectPackage(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return { declared: null, installed: null, isSourceTree: false, packageName: null };
+  }
+  let pkg = {};
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) || {};
+  } catch {
+    return { declared: null, installed: null, isSourceTree: false, packageName: null };
+  }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const declared = deps[PACKAGE_NAME] || null;
+  let installed = null;
+  const nm = path.join(projectRoot, 'node_modules', PACKAGE_NAME, 'package.json');
+  if (fs.existsSync(nm)) {
+    try {
+      installed = JSON.parse(fs.readFileSync(nm, 'utf8')).version || null;
+    } catch {
+      installed = null;
+    }
+  }
+  const isSourceTree =
+    pkg.name === PACKAGE_NAME &&
+    fs.existsSync(path.join(projectRoot, 'src', 'server', 'index.mjs'));
+  return { declared, installed, isSourceTree, packageName: pkg.name || null };
+}
+
+/**
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {string|null}
+ */
+export function fetchLatestNpmVersion(opts = {}) {
+  const timeout = opts.timeoutMs ?? 20_000;
+  const result = spawnSync('npm', ['view', PACKAGE_NAME, 'version'], {
+    encoding: 'utf8',
+    timeout,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (!result || result.status !== 0) return null;
+  const v = (result.stdout || '').trim();
+  return v || null;
+}
+
+/**
+ * Semver-ish compare: true if installed is missing or older than latest.
+ * Handles simple x.y.z only (npm publish tags).
+ * @param {string|null} installed
+ * @param {string} latest
+ */
+export function needsUpdate(installed, latest) {
+  if (!latest) return false;
+  if (!installed) return true;
+  if (installed === latest) return false;
+  const a = installed.split('.').map((n) => parseInt(n, 10) || 0);
+  const b = latest.split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x < y) return true;
+    if (x > y) return false;
+  }
+  return false;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} latest
+ * @param {{ dryRun?: boolean, save?: boolean }} [opts]
+ * @returns {{ ok: boolean, action: string, error?: string, code?: number|null }}
+ */
+export function installPackageInProject(projectRoot, latest, opts = {}) {
+  const dryRun = Boolean(opts.dryRun);
+  const save = opts.save !== false;
+  const spec = `${PACKAGE_NAME}@${latest}`;
+  if (dryRun) {
+    return { ok: true, action: `dry-run: npm install ${spec}${save ? ' --save' : ' --no-save'}` };
+  }
+  const args = ['install', spec];
+  if (save) args.push('--save');
+  else args.push('--no-save');
+  // Prefer clean installs in CI-like envs
+  if (process.env.CI === 'true') args.push('--no-fund', '--no-audit');
+  const result = spawnSync('npm', args, {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    timeout: 10 * 60 * 1000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) {
+    const err = (result.stderr || result.stdout || 'npm install failed').trim().slice(0, 500);
+    return { ok: false, action: `npm install ${spec}`, error: err, code: result.status };
+  }
+  return { ok: true, action: `installed ${spec}`, code: 0 };
+}
+
+/**
+ * Scan roots and optionally install updates.
+ *
+ * @param {{
+ *   brainDir?: string,
+ *   roots?: string[],
+ *   dryRun?: boolean,
+ *   force?: boolean,
+ *   skipThrottle?: boolean,
+ *   intervalMs?: number,
+ *   save?: boolean,
+ * }} [opts]
+ * @returns {Promise<object>}
+ */
+export async function runPackageAutoUpdate(opts = {}) {
+  const enabled = opts.force || isPackageAutoUpdateEnabled();
+  if (!enabled) {
+    return { skipped: true, reason: 'disabled', results: [] };
+  }
+
+  const brainDir = opts.brainDir || path.join(os.homedir(), '.agent', 'skills', 'total-recall');
+  const statePath = packageUpdateStatePath(brainDir);
+  const state = loadUpdateState(statePath);
+  const intervalMs = opts.intervalMs ?? DEFAULT_CHECK_INTERVAL_MS;
+
+  if (!opts.skipThrottle && !opts.force && state.last_check_at) {
+    const elapsed = Date.now() - new Date(state.last_check_at).getTime();
+    if (Number.isFinite(elapsed) && elapsed < intervalMs) {
+      return {
+        skipped: true,
+        reason: 'throttled',
+        next_check_in_ms: intervalMs - elapsed,
+        last_check_at: state.last_check_at,
+        last_latest: state.last_latest,
+        results: state.last_results || [],
+      };
+    }
+  }
+
+  const latest = fetchLatestNpmVersion();
+  if (!latest) {
+    logger.warn('package-auto-update', `Could not resolve npm version for ${PACKAGE_NAME}`);
+    return { skipped: true, reason: 'npm-view-failed', results: [] };
+  }
+
+  const roots = listUpdateRoots({ brainDir, roots: opts.roots });
+  const results = [];
+
+  for (const { root, name, source } of roots) {
+    const info = inspectProjectPackage(root);
+    if (info.isSourceTree) {
+      results.push({
+        name,
+        root,
+        source,
+        status: 'skipped_source_tree',
+        declared: info.declared,
+        installed: info.installed || readPackageJsonVersionField(root),
+        latest,
+        message: 'Source monorepo — use git pull / release tags, not npm tarball into self',
+      });
+      continue;
+    }
+    if (!info.declared && !info.installed) {
+      // Only touch projects that already depend on or install the package
+      results.push({
+        name,
+        root,
+        source,
+        status: 'skipped_no_dependency',
+        declared: null,
+        installed: null,
+        latest,
+      });
+      continue;
+    }
+
+    const installed = info.installed;
+    if (!needsUpdate(installed, latest)) {
+      results.push({
+        name,
+        root,
+        source,
+        status: 'up_to_date',
+        declared: info.declared,
+        installed,
+        latest,
+      });
+      continue;
+    }
+
+    const install = installPackageInProject(root, latest, {
+      dryRun: opts.dryRun,
+      save: opts.save !== false,
+    });
+    results.push({
+      name,
+      root,
+      source,
+      status: install.ok ? (opts.dryRun ? 'would_update' : 'updated') : 'failed',
+      declared: info.declared,
+      installed: install.ok && !opts.dryRun ? latest : installed,
+      previous: installed,
+      latest,
+      action: install.action,
+      error: install.error || null,
+    });
+    if (install.ok && !opts.dryRun) {
+      logger.info(
+        'package-auto-update',
+        `Updated ${name} → ${PACKAGE_NAME}@${latest} (${root})`,
+      );
+    } else if (!install.ok) {
+      logger.warn(
+        'package-auto-update',
+        `Failed updating ${name}: ${install.error || 'unknown'}`,
+      );
+    }
+  }
+
+  const summary = {
+    skipped: false,
+    package: PACKAGE_NAME,
+    latest,
+    checked_at: new Date().toISOString(),
+    root_count: roots.length,
+    updated: results.filter((r) => r.status === 'updated').length,
+    would_update: results.filter((r) => r.status === 'would_update').length,
+    failed: results.filter((r) => r.status === 'failed').length,
+    up_to_date: results.filter((r) => r.status === 'up_to_date').length,
+    results,
+  };
+
+  if (!opts.dryRun) {
+    saveUpdateState(statePath, {
+      last_check_at: summary.checked_at,
+      last_latest: latest,
+      last_results: results.map((r) => ({
+        name: r.name,
+        root: r.root,
+        status: r.status,
+        installed: r.installed,
+        latest: r.latest,
+      })),
+    });
+  }
+
+  return summary;
+}

package/src/core/sandbox.mjs

@@ -90,7 +90,8 @@ export function validateCommand(commandLine) {
  * Executes untrusted agent code in a restricted container or OS-level sandbox.
  */
 export async function runInSandbox(scriptPath, timeoutMs = 5000, options = {}) {
-  const cappedTimeout = Math.min(Math.max(timeoutMs, 1000), 30000);
+  // Allow short timeouts for tests; clamp upper bound for safety.
+  const cappedTimeout = Math.min(Math.max(Number(timeoutMs) || 5000, 200), 30000);
   const allowNetwork = options.allowNetwork === true;
 
   // Restrict environment variables
@@ -104,6 +105,8 @@ export async function runInSandbox(scriptPath, timeoutMs = 5000, options = {}) {
   safeEnv.NODE_OPTIONS = '--experimental-vm-modules';
 
   // OS-specific sandboxing wrappers
+  // Prefer plain node + hard kill timeout. unshare --pid --fork can orphan infinite
+  // loops so the parent wait never ends on Linux CI.
   let cmd = process.execPath;
   let args = ['--no-warnings', scriptPath];
   let tempSbProfilePath = null;
@@ -119,26 +122,25 @@ export async function runInSandbox(scriptPath, timeoutMs = 5000, options = {}) {
         cmd = 'sandbox-exec';
         args = ['-f', tempSbProfilePath, process.execPath, '--no-warnings', scriptPath];
       }
-    } else if (process.platform === 'linux') {
-      // Linux namespace isolation check via unshare
-      const hasUnshare = fs.existsSync('/usr/bin/unshare') || fs.existsSync('/bin/unshare');
-      if (hasUnshare) {
-        cmd = 'unshare';
-        const unshareArgs = ['--mount', '--ipc', '--pid', '--fork'];
-        if (!allowNetwork) {
-          unshareArgs.push('--net');
-        }
-        args = [...unshareArgs, process.execPath, '--no-warnings', scriptPath];
-      }
     }
   } catch (err) {
     logger.warn('sandbox', `Failed to configure OS-specific isolation: ${err.message}. Using default environment limits.`);
   }
 
   return new Promise((resolve) => {
+    let settled = false;
+    const finish = (payload) => {
+      if (settled) return;
+      settled = true;
+      if (tempSbProfilePath && fs.existsSync(tempSbProfilePath)) {
+        try { fs.unlinkSync(tempSbProfilePath); } catch { /* ignore */ }
+      }
+      resolve(payload);
+    };
+
     const proc = spawn(cmd, args, {
       env: safeEnv,
-      timeout: cappedTimeout
+      stdio: ['ignore', 'pipe', 'pipe'],
     });
 
     let stdout = '';
@@ -147,22 +149,35 @@ export async function runInSandbox(scriptPath, timeoutMs = 5000, options = {}) {
     proc.stdout.on('data', (data) => { stdout += data.toString(); });
     proc.stderr.on('data', (data) => { stderr += data.toString(); });
 
+    const timer = setTimeout(() => {
+      try {
+        proc.kill('SIGKILL');
+      } catch { /* ignore */ }
+      // Also try process group if detached later
+      try {
+        if (proc.pid) process.kill(proc.pid, 'SIGKILL');
+      } catch { /* ignore */ }
+      finish({
+        success: false,
+        output: stderr || stdout || `Sandbox timeout after ${cappedTimeout}ms`,
+        code: null,
+        signal: 'SIGKILL',
+        timedOut: true,
+      });
+    }, cappedTimeout);
+
     proc.on('close', (code, signal) => {
-      if (tempSbProfilePath && fs.existsSync(tempSbProfilePath)) {
-        try { fs.unlinkSync(tempSbProfilePath); } catch {}
-      }
+      clearTimeout(timer);
       if (code === 0) {
-        resolve({ success: true, output: stdout, code, signal });
+        finish({ success: true, output: stdout, code, signal });
       } else {
-        resolve({ success: false, output: stderr || stdout, code, signal });
+        finish({ success: false, output: stderr || stdout, code, signal });
       }
     });
 
     proc.on('error', (err) => {
-      if (tempSbProfilePath && fs.existsSync(tempSbProfilePath)) {
-        try { fs.unlinkSync(tempSbProfilePath); } catch {}
-      }
-      resolve({ success: false, output: err.message, code: -1 });
+      clearTimeout(timer);
+      finish({ success: false, output: err.message, code: -1 });
     });
   });
 }

package/src/server/route-manifest.json

@@ -263,10 +263,38 @@
     "method": "GET",
     "path": "/api/memory/stats"
   },
+  {
+    "method": "GET",
+    "path": "/api/mesh/election/history"
+  },
+  {
+    "method": "POST",
+    "path": "/api/mesh/election/log"
+  },
   {
     "method": "POST",
     "path": "/api/mesh/election/refresh"
   },
+  {
+    "method": "GET",
+    "path": "/api/mesh/interfaces"
+  },
+  {
+    "method": "GET",
+    "path": "/api/mesh/io"
+  },
+  {
+    "method": "GET",
+    "path": "/api/mesh/lan"
+  },
+  {
+    "method": "POST",
+    "path": "/api/mesh/lan/register"
+  },
+  {
+    "method": "GET",
+    "path": "/api/mesh/latency"
+  },
   {
     "method": "GET",
     "path": "/api/mesh/leader"
@@ -683,6 +711,10 @@
     "method": "GET",
     "path": "/api/webhooks/events"
   },
+  {
+    "method": "POST",
+    "path": "/api/webhooks/events/:id/redeliver"
+  },
   {
     "method": "POST",
     "path": "/api/webhooks/test/:provider"

package/src/server/routes/update.mjs

@@ -1,39 +1,105 @@
 import { Router } from 'express';
-import { requireAuth } from '../auth.mjs';
+import { requireAuth, requireScope } from '../auth.mjs';
 import { spawn } from 'node:child_process';
+import path from 'node:path';
 import { ROOT, serverError } from './_shared.mjs';
+import { brainDir as configBrainDir } from '../../core/config.mjs';
+import {
+  PACKAGE_NAME,
+  fetchLatestNpmVersion,
+  inspectProjectPackage,
+  listUpdateRoots,
+  runPackageAutoUpdate,
+  needsUpdate,
+  isPackageAutoUpdateEnabled,
+} from '../../core/package-auto-update.mjs';
 
 const router = Router();
 
-router.get('/api/update/check', requireAuth, async (req, res) => {
+router.get('/api/update/check', requireAuth, async (_req, res) => {
   try {
-    const pkg = await import('../../../package.json', { with: { type: 'json' } });
-    const current = pkg.default.version;
-    const proc = spawn('npm', ['view', 'total-recall-brain', 'version'], { stdio: ['ignore', 'pipe', 'ignore'] });
-    let latest = '';
-    proc.stdout.on('data', d => latest += d.toString());
-    proc.on('close', () => {
-      latest = latest.trim();
-      res.json({
-        current,
-        latest,
-        update_available: current !== latest && latest.length > 0
-      });
+    // Host package (this install)
+    let current = null;
+    try {
+      const pkg = await import('../../../package.json', { with: { type: 'json' } });
+      current = pkg.default.version;
+    } catch {
+      current = null;
+    }
+
+    const latest = fetchLatestNpmVersion() || '';
+    const roots = listUpdateRoots({ brainDir: configBrainDir });
+    const projects = roots.map(({ root, name, source }) => {
+      const info = inspectProjectPackage(root);
+      return {
+        name,
+        root,
+        source,
+        declared: info.declared,
+        installed: info.installed,
+        is_source_tree: info.isSourceTree,
+        update_available: !info.isSourceTree && needsUpdate(info.installed, latest),
+      };
+    });
+
+    const consumersBehind = projects.filter((p) => p.update_available).length;
+
+    res.json({
+      package: PACKAGE_NAME,
+      current,
+      latest,
+      update_available: Boolean(latest && current && current !== latest) || consumersBehind > 0,
+      auto_update_enabled: isPackageAutoUpdateEnabled(),
+      projects,
+      consumers_behind: consumersBehind,
     });
   } catch (err) {
     serverError(res, err);
   }
 });
 
-router.post('/api/update/run', requireAuth, async (req, res) => {
+/**
+ * POST /api/update/run
+ * Body optional: { dryRun?: boolean, force?: boolean, roots?: string[] }
+ * Runs multi-repo npm install for total-recall-brain@latest via package-auto-update.
+ */
+router.post('/api/update/run', requireAuth, requireScope('config:write'), async (req, res) => {
   try {
-    const proc = spawn('npm', ['install', 'total-recall-brain@latest', '--no-save'], {
-      cwd: ROOT,
-      detached: true,
-      stdio: 'ignore'
+    const dryRun = Boolean(req.body?.dryRun);
+    const force = req.body?.force !== false;
+    const roots = Array.isArray(req.body?.roots) ? req.body.roots : undefined;
+
+    // Fire multi-project updater (awaits — install can take minutes; client should timeout high)
+    const summary = await runPackageAutoUpdate({
+      brainDir: configBrainDir,
+      roots,
+      dryRun,
+      force,
+      skipThrottle: true,
+      save: true,
+    });
+
+    // Also kick a local install in ROOT when this host is a consumer (non-source)
+    const hostInfo = inspectProjectPackage(ROOT);
+    if (!hostInfo.isSourceTree && (hostInfo.declared || hostInfo.installed) && !dryRun) {
+      const latest = summary.latest || fetchLatestNpmVersion();
+      if (latest && needsUpdate(hostInfo.installed, latest)) {
+        const proc = spawn('npm', ['install', `${PACKAGE_NAME}@${latest}`, '--save'], {
+          cwd: ROOT,
+          detached: true,
+          stdio: 'ignore',
+        });
+        proc.unref();
+      }
+    }
+
+    res.json({
+      updating: !dryRun,
+      message: dryRun
+        ? 'Dry-run complete — see projects list'
+        : 'Package auto-update finished for registered projects',
+      summary,
     });
-    proc.unref();
-    res.json({ updating: true, message: 'Update started in background. Daemon will restart automatically.' });
   } catch (err) {
     serverError(res, err);
   }