total-recall-brain 3.28.2 → 3.30.0

package/src/core/app-deploy/upgrade.mjs

@@ -0,0 +1,256 @@
+/**
+ * Total Recall — Capability Deployment Upgrader
+ *
+ * Implements Phase 3 of CAPABILITY_DEPLOYMENT_PLUGINS:
+ * - Structural-only migration between capability versions
+ * - Preservation of tenant-private data and user customizations
+ * - Rollback on interrupted or failing upgrade
+ * - Truthful status and append-only event logging
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { createDeploymentPlan } from './plan.mjs';
+import { applyDeploymentPlan, resolveAppVaultDir, formatSsssDocument } from './apply.mjs';
+import { resolveCapabilitySource } from './source.mjs';
+
+export class AppUpgradeError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'AppUpgradeError';
+    this.details = details;
+  }
+}
+
+/**
+ * Reads the installed capability record from the target app vault.
+ * @param {string} targetDir
+ * @param {string} capabilityId
+ * @returns {object|null}
+ */
+export function getInstalledCapabilityRecord(targetDir, capabilityId) {
+  const vaultDir = resolveAppVaultDir(targetDir);
+  const recordPath = path.join(vaultDir, 'system', 'capabilities', `${capabilityId}.md`);
+  if (!fs.existsSync(recordPath)) return null;
+
+  const content = fs.readFileSync(recordPath, 'utf8');
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) return null;
+
+  const raw = frontmatterMatch[1];
+  const record = {};
+  for (const line of raw.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let val = line.slice(colonIdx + 1).trim();
+    if (val.startsWith('"') && val.endsWith('"')) {
+      val = val.slice(1, -1);
+    } else if (val.startsWith('[') || val.startsWith('{')) {
+      try {
+        val = JSON.parse(val);
+      } catch {}
+    }
+    record[key] = val;
+  }
+  return record;
+}
+
+/**
+ * Upgrades an installed capability in an application to a new version or pinned hash.
+ *
+ * @param {string} capabilityId - ID of capability to upgrade
+ * @param {object} options
+ * @param {string} options.to - New source path, git ref, or pinned package
+ * @param {string} [options.target] - Target app directory (default: cwd)
+ * @param {string} [options.adapter] - Adapter override
+ * @param {boolean} [options.dryRun] - Preflight only
+ * @param {string} [options.actor] - SSSS actor
+ * @returns {Promise<{
+ *   success: boolean,
+ *   capability_id: string,
+ *   from_version: string,
+ *   to_version: string,
+ *   plan_hash: string,
+ *   removed_files: string[],
+ *   applied_files: number,
+ *   dryRun?: boolean
+ * }>}
+ */
+export async function upgradeCapability(capabilityId, options = {}) {
+  const targetDir = options.target || process.cwd();
+  const actor = options.actor || 'total-recall/app-deploy';
+
+  if (!options.to) {
+    throw new AppUpgradeError('Missing target source (--to) for upgrade');
+  }
+
+  // 1. Verify existing capability installation
+  const existingRecord = getInstalledCapabilityRecord(targetDir, capabilityId);
+  if (!existingRecord) {
+    throw new AppUpgradeError(
+      `Capability '${capabilityId}' is not installed in target application (${targetDir})`
+    );
+  }
+
+  const fromVersion = existingRecord.version || 'unknown';
+  const oldFiles = Array.isArray(existingRecord.files) ? existingRecord.files : [];
+
+  // 2. Staged upgrade with rollback protection
+  const backupDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tr-upgrade-backup-'));
+  const obsoleteBackups = [];
+  const vaultDir = resolveAppVaultDir(targetDir);
+  const capInstallDir = path.join(vaultDir, 'system', 'capabilities');
+  const eventDir = path.join(vaultDir, 'system', 'events');
+  let newPlan = null;
+
+  try {
+    newPlan = await createDeploymentPlan(options.to, {
+      target: targetDir,
+      adapter: options.adapter || existingRecord.adapter || 'ssss-app',
+      pluginResolver: options.pluginResolver
+    });
+
+    if (!newPlan.valid) {
+      throw new AppUpgradeError(
+        `Cannot upgrade capability: new version produces ${newPlan.conflicts?.length || 0} conflict(s)`
+      );
+    }
+
+    // Identify files from old version that no longer exist in new version
+    const newFilePaths = new Set((newPlan.file_operations || []).map((op) => op.path));
+    const obsoleteFiles = oldFiles.filter((f) => !newFilePaths.has(f.path));
+
+    // If dry-run, return planned diff
+    if (options.dryRun) {
+      fs.rmSync(backupDir, { recursive: true, force: true });
+      newPlan.cleanup?.();
+      return {
+        success: true,
+        dryRun: true,
+        capability_id: capabilityId,
+        from_version: fromVersion,
+        to_version: newPlan.capabilities[0]?.version || 'unknown',
+        plan_hash: newPlan.plan_hash,
+        removed_files: obsoleteFiles.map((f) => f.path),
+        applied_files: newPlan.file_operations?.length || 0
+      };
+    }
+
+    // Backup obsolete files before removing them
+    for (const obs of obsoleteFiles) {
+      const targetFilePath = path.join(targetDir, obs.path);
+      if (fs.existsSync(targetFilePath)) {
+        const backupPath = path.join(backupDir, obs.path);
+        fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+        fs.copyFileSync(targetFilePath, backupPath);
+        obsoleteBackups.push({ targetPath: targetFilePath, backupPath });
+        // Remove obsolete capability file
+        fs.rmSync(targetFilePath, { force: true });
+      }
+    }
+
+    // Apply new version via applyDeploymentPlan
+    const applyResult = await applyDeploymentPlan(newPlan, {
+      target: targetDir,
+      actor,
+      force: true
+    });
+
+    // Record upgrade event envelope
+    const toVersion = newPlan.capabilities[0]?.version || 'unknown';
+    const upgradeEvent = {
+      type: 'event',
+      domain: 'ssss.capability',
+      action: 'upgraded',
+      timestamp: new Date().toISOString(),
+      actor,
+      target: targetDir,
+      payload: {
+        capability_id: capabilityId,
+        from_version: fromVersion,
+        to_version: toVersion,
+        plan_hash: newPlan.plan_hash
+      }
+    };
+
+    fs.mkdirSync(eventDir, { recursive: true });
+    fs.appendFileSync(
+      path.join(eventDir, 'capability-events.jsonl'),
+      JSON.stringify(upgradeEvent) + '\n',
+      'utf8'
+    );
+
+    // Clean up backup directory
+    fs.rmSync(backupDir, { recursive: true, force: true });
+    newPlan.cleanup?.();
+
+    return {
+      success: true,
+      capability_id: capabilityId,
+      from_version: fromVersion,
+      to_version: toVersion,
+      plan_hash: newPlan.plan_hash,
+      removed_files: obsoleteFiles.map((f) => f.path),
+      applied_files: applyResult.applied_files
+    };
+  } catch (err) {
+    // Rollback obsolete files that were removed
+    for (const b of obsoleteBackups) {
+      try {
+        if (fs.existsSync(b.backupPath)) {
+          fs.mkdirSync(path.dirname(b.targetPath), { recursive: true });
+          fs.copyFileSync(b.backupPath, b.targetPath);
+        }
+      } catch {}
+    }
+
+    // Record truthful failure status
+    try {
+      if (fs.existsSync(capInstallDir)) {
+        const failedRecord = {
+          ...existingRecord,
+          status: 'upgrade_failed',
+          updated_at: new Date().toISOString(),
+          error: err.message
+        };
+        const failedMd = formatSsssDocument(
+          failedRecord,
+          `# Upgrade Failed\n\nAttempt to upgrade to version from '${options.to}' failed: ${err.message}\n`
+        );
+        fs.writeFileSync(path.join(capInstallDir, `${capabilityId}.md`), failedMd, 'utf8');
+      }
+
+      const failEvent = {
+        type: 'event',
+        domain: 'ssss.capability',
+        action: 'upgrade_failed',
+        timestamp: new Date().toISOString(),
+        actor,
+        target: targetDir,
+        payload: {
+          capability_id: capabilityId,
+          from_version: fromVersion,
+          error: err.message
+        }
+      };
+      fs.appendFileSync(
+        path.join(eventDir, 'capability-events.jsonl'),
+        JSON.stringify(failEvent) + '\n',
+        'utf8'
+      );
+    } catch {}
+
+    try {
+      if (fs.existsSync(backupDir)) fs.rmSync(backupDir, { recursive: true, force: true });
+      newPlan.cleanup?.();
+    } catch {}
+
+    throw new AppUpgradeError(`Capability upgrade failed: ${err.message}`, {
+      capability_id: capabilityId,
+      originalError: err
+    });
+  }
+}

package/src/core/app-deploy/verify.mjs

@@ -0,0 +1,213 @@
+/**
+ * Total Recall — Capability Deployment Verifier
+ *
+ * Implements Phase 3 of CAPABILITY_DEPLOYMENT_PLUGINS:
+ * - Verification of installed capability source file hashes and drift detection
+ * - Conformance of SSSS installation records, access grants, and event logs
+ * - Verification of application shell gates and entrypoints
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { resolveAppVaultDir } from './apply.mjs';
+import {
+  AppCapabilityInstallationSchema,
+  AccessGrantSchema
+} from '../schema.mjs';
+
+/**
+ * Verifies an application's capability deployments, integrity, and conformance.
+ *
+ * @param {string} targetDir - Application root directory
+ * @param {object} [options]
+ * @param {boolean} [options.checkFiles=true] - Verify sha256 hashes of all deployed files
+ * @returns {Promise<{
+ *   valid: boolean,
+ *   target: string,
+ *   vault: string,
+ *   capabilities: Array<{
+ *     id: string,
+ *     version: string,
+ *     status: string,
+ *     files_checked: number,
+ *     files_intact: number,
+ *     drift: Array<{ path: string, expected_sha: string, actual_sha?: string, missing?: boolean }>
+ *   }>,
+ *   grants: Array<{ id: string, valid: boolean, scopes: string[] }>,
+ *   events_count: number,
+ *   errors: string[]
+ * }>}
+ */
+export async function verifyApplication(targetDir = process.cwd(), options = {}) {
+  const resolvedTarget = path.resolve(targetDir);
+  const checkFiles = options.checkFiles !== false;
+  const errors = [];
+
+  if (!fs.existsSync(resolvedTarget)) {
+    throw new Error(`Target application directory does not exist: ${resolvedTarget}`);
+  }
+
+  const vaultDir = resolveAppVaultDir(resolvedTarget);
+  const capInstallDir = path.join(vaultDir, 'system', 'capabilities');
+  const grantDir = path.join(vaultDir, 'system', 'grants');
+  const eventDir = path.join(vaultDir, 'system', 'events');
+
+  const capabilitiesReport = [];
+
+  // 1. Verify Installed Capabilities
+  if (fs.existsSync(capInstallDir)) {
+    const files = fs.readdirSync(capInstallDir).filter((f) => f.endsWith('.md'));
+    for (const f of files) {
+      const capPath = path.join(capInstallDir, f);
+      const content = fs.readFileSync(capPath, 'utf8');
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!match) {
+        errors.push(`Malformed capability record '${f}': missing YAML frontmatter`);
+        continue;
+      }
+
+      const raw = match[1];
+      const record = {};
+      for (const line of raw.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1) continue;
+        const key = line.slice(0, colonIdx).trim();
+        let val = line.slice(colonIdx + 1).trim();
+        if (val.startsWith('"') && val.endsWith('"')) {
+          val = val.slice(1, -1);
+        } else if (val.startsWith('[') || val.startsWith('{')) {
+          try {
+            val = JSON.parse(val);
+          } catch {}
+        }
+        record[key] = val;
+      }
+
+      const validation = AppCapabilityInstallationSchema.safeParse(record);
+      if (!validation.success) {
+        errors.push(
+          `Invalid capability installation schema in '${f}': ${validation.error.issues.map((i) => i.message).join('; ')}`
+        );
+      }
+
+      const capId = record.capability_id || path.basename(f, '.md');
+      const version = record.version || 'unknown';
+      const status = record.status || 'unknown';
+      const fileList = Array.isArray(record.files) ? record.files : [];
+      const drift = [];
+      let intactCount = 0;
+
+      if (checkFiles) {
+        for (const fileDesc of fileList) {
+          const targetFilePath = path.join(resolvedTarget, fileDesc.path);
+          if (!fs.existsSync(targetFilePath)) {
+            drift.push({
+              path: fileDesc.path,
+              expected_sha: fileDesc.sha256,
+              missing: true
+            });
+          } else {
+            const actualBytes = fs.readFileSync(targetFilePath);
+            const actualSha = crypto.createHash('sha256').update(actualBytes).digest('hex');
+            if (actualSha !== fileDesc.sha256) {
+              drift.push({
+                path: fileDesc.path,
+                expected_sha: fileDesc.sha256,
+                actual_sha: actualSha
+              });
+            } else {
+              intactCount++;
+            }
+          }
+        }
+      }
+
+      if (status !== 'installed') {
+        errors.push(`Capability '${capId}' has non-ready status: '${status}'`);
+      }
+      if (drift.length > 0) {
+        errors.push(
+          `Capability '${capId}' has ${drift.length} drifted/missing file(s): ${drift.map((d) => d.path).join(', ')}`
+        );
+      }
+
+      capabilitiesReport.push({
+        id: capId,
+        version,
+        status,
+        files_checked: fileList.length,
+        files_intact: intactCount,
+        drift
+      });
+    }
+  }
+
+  // 2. Verify Access Grants
+  const grantsReport = [];
+  if (fs.existsSync(grantDir)) {
+    const files = fs.readdirSync(grantDir).filter((f) => f.endsWith('.md'));
+    for (const f of files) {
+      const grantPath = path.join(grantDir, f);
+      const content = fs.readFileSync(grantPath, 'utf8');
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!match) continue;
+
+      const raw = match[1];
+      const record = {};
+      for (const line of raw.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1) continue;
+        const key = line.slice(0, colonIdx).trim();
+        let val = line.slice(colonIdx + 1).trim();
+        if (val.startsWith('"') && val.endsWith('"')) {
+          val = val.slice(1, -1);
+        } else if (val.startsWith('[') || val.startsWith('{')) {
+          try {
+            val = JSON.parse(val);
+          } catch {}
+        }
+        record[key] = val;
+      }
+
+      const validation = AccessGrantSchema.safeParse(record);
+      if (!validation.success) {
+        errors.push(`Invalid access grant '${f}': ${validation.error.issues.map((i) => i.message).join('; ')}`);
+      }
+
+      grantsReport.push({
+        id: record.grantee || path.basename(f, '.md'),
+        valid: validation.success,
+        scopes: record.scopes || []
+      });
+    }
+  }
+
+  // 3. Verify SSSS Event Ledger
+  let eventsCount = 0;
+  const eventLogFile = path.join(eventDir, 'capability-events.jsonl');
+  if (fs.existsSync(eventLogFile)) {
+    const lines = fs.readFileSync(eventLogFile, 'utf8').trim().split('\n').filter(Boolean);
+    eventsCount = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+      try {
+        const envelope = JSON.parse(lines[i]);
+        if (!envelope.type || !envelope.domain || !envelope.action) {
+          errors.push(`Invalid SSSS event envelope at line ${i + 1} of capability-events.jsonl`);
+        }
+      } catch (parseErr) {
+        errors.push(`Corrupt JSON line in capability-events.jsonl at line ${i + 1}: ${parseErr.message}`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    target: resolvedTarget,
+    vault: vaultDir,
+    capabilities: capabilitiesReport,
+    grants: grantsReport,
+    events_count: eventsCount,
+    errors
+  };
+}

package/src/core/bound-hosts.mjs

@@ -9,7 +9,7 @@
  * The Mac Mini is the worked example. Its brain started 2026-08-13 while
  * Tailscale was still starting, so `getMeshIp()` returned null and the bind
  * fell back to loopback only. A week later Tailscale answers perfectly, so the
- * card derived `listen_hosts = [127.0.0.1, 100.64.0.2]`, recommended the mesh
+ * card derived `listen_hosts = [127.0.0.1, 100.64.0.10]`, recommended the mesh
  * URL, and drew a QR for an address nothing has ever listened on -- while
  * reporting no warning, because every check downstream was reading the guess.
  *

package/src/core/brain-registry.mjs

@@ -0,0 +1,146 @@
+/**
+ * Every brain this machine knows, and which of them are switched on.
+ *
+ * A machine carries one global brain plus any number of project brains
+ * (registered with `brain register`, or simply present in the working
+ * directory). Until now nothing could be excluded: recall always read the
+ * global brain and whichever project brain the cwd resolved to. A brain that
+ * is switched off is skipped by recall; listing still shows it.
+ *
+ * On/off state lives in one file in the global brain,
+ * `config/brain-toggles.json`, keyed by resolved brain directory, so the same
+ * switch applies from every repository on the machine. A brain is on unless it
+ * has been switched off — nothing changes for anyone who never uses this.
+ *
+ * Portability (open source): no brain, repo or path is hardcoded.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function globalBrainDirFor(env = process.env) {
+  const agentDir = env.AGENT_DIR || path.join(os.homedir(), '.agent');
+  return path.join(agentDir, 'skills', 'total-recall');
+}
+
+function togglesPath(globalBrainDir) {
+  return path.join(globalBrainDir, 'config', 'brain-toggles.json');
+}
+
+function registryPath(globalBrainDir) {
+  return path.join(globalBrainDir, 'config', 'project-registry.json');
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/** `{ [resolvedBrainDir]: false }` for every brain switched off. */
+export function readBrainToggles(globalBrainDir = globalBrainDirFor()) {
+  const data = readJson(togglesPath(globalBrainDir), {});
+  return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+}
+
+export function isBrainEnabled(brainDir, { globalBrainDir = globalBrainDirFor(), toggles = null } = {}) {
+  const state = toggles || readBrainToggles(globalBrainDir);
+  return state[path.resolve(brainDir)] !== false;
+}
+
+/** Switch a brain on or off. Written atomically; only "off" entries are stored. */
+export function setBrainEnabled(brainDir, enabled, { globalBrainDir = globalBrainDirFor() } = {}) {
+  const state = readBrainToggles(globalBrainDir);
+  const key = path.resolve(brainDir);
+  if (enabled) delete state[key];
+  else state[key] = false;
+
+  const file = togglesPath(globalBrainDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return { brainDir: key, enabled: !!enabled };
+}
+
+function countMarkdown(dir) {
+  let count = 0;
+  const walk = (current) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.md')) count += 1;
+    }
+  };
+  walk(dir);
+  return count;
+}
+
+/**
+ * Every brain on this machine: the global one, each registered project brain,
+ * and the active project brain even when it was never registered.
+ *
+ * @param {{ globalBrainDir?: string, activeProject?: { brainDir: string, projectRoot?: string } | null }} [options]
+ * @returns {Array<{ name: string, kind: 'global'|'project', brainDir: string, root: string|null,
+ *   enabled: boolean, active: boolean, exists: boolean, nodes: number }>}
+ */
+export function listLocalBrains(options = {}) {
+  const globalBrainDir = options.globalBrainDir || globalBrainDirFor();
+  const activeProject = options.activeProject === undefined ? null : options.activeProject;
+  const toggles = readBrainToggles(globalBrainDir);
+  const activeDir = activeProject ? path.resolve(activeProject.brainDir) : null;
+
+  const describe = (name, kind, brainDir, root) => {
+    const exists = fs.existsSync(brainDir);
+    return {
+      name,
+      kind,
+      brainDir: path.resolve(brainDir),
+      root: root || null,
+      enabled: toggles[path.resolve(brainDir)] !== false,
+      active: kind === 'global' ? !activeDir : path.resolve(brainDir) === activeDir,
+      exists,
+      nodes: exists ? countMarkdown(path.join(brainDir, 'memory-vault')) : 0,
+    };
+  };
+
+  const brains = [describe('global', 'global', globalBrainDir, null)];
+  const registry = readJson(registryPath(globalBrainDir), []);
+  for (const entry of Array.isArray(registry) ? registry : []) {
+    if (!entry?.brainDir) continue;
+    if (brains.some((b) => b.brainDir === path.resolve(entry.brainDir))) continue;
+    brains.push(describe(entry.name || path.basename(entry.path || entry.brainDir), 'project', entry.brainDir, entry.path));
+  }
+  if (activeProject && !brains.some((b) => b.brainDir === activeDir)) {
+    const root = activeProject.projectRoot || null;
+    brains.push(describe(root ? path.basename(root) : 'project', 'project', activeProject.brainDir, root));
+  }
+  return brains;
+}
+
+/**
+ * Find a brain by `global`, its name, its repo path or its brain path.
+ * Names are matched case-insensitively; an ambiguous name returns null.
+ */
+export function findLocalBrain(brains, query) {
+  const wanted = String(query || '').trim();
+  if (!wanted) return null;
+  if (wanted.toLowerCase() === 'global') return brains.find((b) => b.kind === 'global') || null;
+
+  const asPath = path.resolve(wanted);
+  const byPath = brains.find((b) => b.brainDir === asPath || (b.root && path.resolve(b.root) === asPath));
+  if (byPath) return byPath;
+
+  const byName = brains.filter((b) => b.name.toLowerCase() === wanted.toLowerCase());
+  return byName.length === 1 ? byName[0] : null;
+}

package/src/core/brain-state.json

@@ -29,6 +29,7 @@
     "backups",
     "browser-profile",
     "skills-registry",
+    "plugins",
     ".snapshots",
     ".git",
     "node_modules"