total-recall-brain 3.40.1 → 3.40.2

package/src/cli/connect.mjs

@@ -115,6 +115,11 @@ export const CLIENTS = {
     // Grok discovers repository skills in <project>/.agents/skills.
     skillsProjection: { scope: 'project', dir: path.join('.agents', 'skills') }
   },
+  muse: {
+    label: 'Muse Code',
+    mode: 'symlink',
+    target: 'AGENTS.md'
+  },
   replit: {
     label: 'Replit Agent',
     mode: 'file',

package/src/cli/context.mjs

@@ -41,8 +41,9 @@ export default async function context(args = []) {
   const nodes = own ? mergeGlobalRuleNodes(getNodes(path.join(own, 'memory-vault')), global ? getNodes(path.join(global, 'memory-vault')) : []) :
     getNodes(path.join(global, 'memory-vault')).map(n => ({ ...n, _layer: 'global' }));
   const skillsDir = path.dirname(own || global);
+  const derivedDir = own ? path.join(own, 'memory-derived') : (global ? path.join(global, 'memory-derived') : null);
   const result = await compileContext({ query, actions, nodes, includeKnowledge, budget: { total: budget }, projectRoot: process.cwd(),
-    contributions: legacyRuleContributions(skillsDir), versionInputs: surfaceInputsHash({ skillsDir }) });
+    derivedDir, contributions: legacyRuleContributions(skillsDir), versionInputs: surfaceInputsHash({ skillsDir }) });
   if (debug && format === 'text') throw new Error('--debug requires --format json');
   const response = capsuleResponse(result, { total: budget, debug, format });
   if (!response.ready && !debug) {

package/src/cli/daemon.mjs

@@ -56,8 +56,10 @@ function printHelp() {
 
   Commands:
     start     Start the background Active Intelligence Daemon
+    ensure    Enable the managed daemon; --restart reloads current source
     stop      Stop the background daemon
     status    Show daemon status + recent log entries
+    logs      Read daemon logs (--lines N, default 50)
 
   The daemon runs a durable task loop that:
     • Ingests IDE conversation logs (Claude Code, Codex, Gemini, etc.)
@@ -207,6 +209,39 @@ export default async function daemon(args) {
   const useLaunchd = !useSystemd && hasLaunchd();
 
   switch (subcommand) {
+    case 'ensure': {
+      if(!useSystemd)throw new Error('Managed daemon ensure currently requires systemd on the daemon host');
+      // A detached worker can hold the same brain lock while systemd reports a
+      // successful short-lived start. Stop that verified owner before takeover.
+      const managed=spawnSync('systemctl',['show','total-recall-daemon','--property=MainPID','--value'],{encoding:'utf8'});
+      if(managed.status!==0)throw new Error('Cannot inspect managed daemon');
+      const owner=readPid(),managedPid=Number(managed.stdout.trim());
+      if(owner && (owner!==managedPid || args.includes('--restart'))){
+        if(owner===managedPid)execFileSync('systemctl',['stop','total-recall-daemon'],{stdio:'inherit'});
+        else if(!await stopDaemon())throw new Error('Cannot stop verified detached daemon');
+      }
+      execFileSync('systemctl',['enable','--now','total-recall-daemon'],{stdio:'inherit'});
+      await new Promise(resolve=>setTimeout(resolve,3000));
+      const active=spawnSync('systemctl',['is-active','--quiet','total-recall-daemon']);
+      const current=spawnSync('systemctl',['show','total-recall-daemon','--property=MainPID','--value'],{encoding:'utf8'});
+      const pid=readPid();
+      if(active.status!==0 || !pid || pid!==Number(current.stdout?.trim()))throw new Error('Managed daemon did not retain ownership of the brain lock');
+      console.log(JSON.stringify({ok:true,manager:'systemd',pid,enabled:true}));
+      break;
+    }
+    case 'logs': {
+      const index = args.indexOf('--lines');
+      const lines = index < 0 ? 50 : Number(args[index + 1]);
+      if (!Number.isInteger(lines) || lines < 1 || lines > 10000) throw new Error('--lines must be an integer from 1 to 10000');
+      if (useSystemd) {
+        const result = spawnSync('journalctl', ['-u', 'total-recall-daemon.service', '-n', String(lines), '--no-pager'], { stdio: 'inherit' });
+        if (result.error || result.status !== 0) throw new Error('Could not read the daemon journal');
+      } else {
+        if (!fs.existsSync(LOG_FILE)) throw new Error('No daemon log exists');
+        console.log(fs.readFileSync(LOG_FILE, 'utf8').trimEnd().split('\n').slice(-lines).join('\n'));
+      }
+      break;
+    }
     case 'start':
       if (useSystemd) systemdStart();
       else if (useLaunchd) launchctlStart();
@@ -224,7 +259,7 @@ export default async function daemon(args) {
       break;
     default:
       console.error(`  Unknown daemon command: ${subcommand}`);
-      console.error(`  Valid commands: start, stop, status`);
+      console.error(`  Valid commands: start, ensure, stop, status, logs`);
       process.exit(1);
   }
 }

package/src/cli/doctor.mjs

@@ -18,6 +18,7 @@ import { fileURLToPath, URL } from 'node:url';
 import { getGlobalBrainDir } from './agent-dir.mjs';
 import { processIdentity, verifyListener } from '../core/startup-health.mjs';
 import { loadKnownRepoRoots } from '../core/skills-registry.mjs';
+import { inspectRequiredPlugins } from '../core/required-plugins.mjs';
 
 // ─── Formatting & UI Helpers ────────────────────────────────────────────────
 function log(msg)     { console.log(`  ${msg}`); }
@@ -91,6 +92,11 @@ export default async function doctor() {
 
   let warnings = 0;
   let failures = 0;
+  const { resolveBrainDir } = await import('./agent-dir.mjs');
+  for (const brain of new Set([getGlobalBrainDir(), resolveBrainDir()])) {
+    const required = inspectRequiredPlugins(brain);
+    if (required.status !== 'ready') { logFail(`${brain}: ${required.errors.join('; ')}`); failures++; }
+  }
 
   // ── Step 1: System Hardware Check ──
   hr();

package/src/cli/harness.mjs

@@ -23,6 +23,9 @@ Available Harness IDs:
   grok                      xAI Grok Build CLI (Autonomous coding, inspection, shell execution)
   gemini                    Google Gemini CLI (Fast utilities & completion chaining)
   ollama                    Ollama Local LLM (Local neural reasoning, zero API cost)
+  hermes                    Hermes Agent Runtime (Autonomous supervisor & messaging gateway)
+  dsh                       DeepSeek Harness DSH (High-throughput reasoning engine)
+  openclaw                  OpenClaw Agent Bridge (Multi-channel messaging & tool execution)
 
 Examples:
   npx total-recall harness list

package/src/cli/help.mjs

@@ -122,6 +122,32 @@ export default async function run(argv) {
       console.log('\n' + '─'.repeat(60) + '\n');
     }
   } else {
+    // Semantic CLI search fallback across all core, plugin, and composed verbs
+    try {
+      const { queryCliSemanticIndex } = await import('../core/cli-semantic-index.mjs');
+      const matches = await queryCliSemanticIndex(requestedTopic || topic, { limit: 6, minScore: 0.25 });
+      if (matches.length > 0) {
+        if (isJson) {
+          console.log(JSON.stringify({ topic: requestedTopic || topic, matches }, null, 2));
+          return;
+        }
+        console.log(`\n\x1b[34m=== Total Recall Semantic Help: "${requestedTopic || topic}" ===\x1b[0m\n`);
+        console.log('  Top matching CLI verbs:\n');
+        for (const m of matches) {
+          const badge = m.category === 'plugin'
+            ? `\x1b[35m[plugin:${m.namespace}]\x1b[0m`
+            : (m.category === 'composed' ? `\x1b[36m[composed]\x1b[0m` : `\x1b[32m[core]\x1b[0m`);
+          console.log(`  • \x1b[1m${m.verb}\x1b[0m ${badge}`);
+          console.log(`    ${m.description}`);
+          console.log(`    \x1b[2mUsage: ${m.usage}\x1b[0m\n`);
+        }
+        console.log('─'.repeat(60) + '\n');
+        return;
+      }
+    } catch {
+      /* Fallback to default not found message */
+    }
+
     console.error(`  ❌ Error: No help section found for topic or command: "${topic}"`);
     console.error(`  Run 'npx total-recall help' to see the complete list of commands.`);
     process.exit(1);

package/src/cli/init.mjs

@@ -244,10 +244,10 @@ export default async function init(args) {
   logOk(`Base directory structure ready (${created} created, ${dirs.length - created} already existed)`);
 
   // Auth is a required scaffold plugin. Existing installations are preserved.
-  const authSource = path.join(ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins', 'auth');
-  const authTarget = path.join(brainDir, 'plugins', 'auth');
-  if (!fs.existsSync(path.join(authSource, 'plugin.json'))) throw new Error('Required auth scaffold is missing');
-  if (!fs.existsSync(authTarget) && !opts.dryRun) fs.cpSync(authSource, authTarget, { recursive: true, errorOnExist: true, force: false });
+  if (!opts.dryRun) {
+    const { ensureRequiredPlugins } = await import('../core/required-plugins.mjs');
+    ensureRequiredPlugins(brainDir);
+  }
 
   // Every scaffold plugin's node_modules are wired in Step 2.5, after the skill
   // tree has been copied into the brain (see the note there).

package/src/cli/memory-entry.mjs

@@ -26,6 +26,7 @@ const handlers = {
 
 export async function main(args = []) {
   const [command, ...rest] = args;
+  if (command === 'secret' || command === 'secrets') throw new Error('Credential commands belong to total-recall auth secret');
   if (!command || ['help', '--help', '-h'].includes(command)) {
     console.log(`Total Recall — portable memory and instructions
 Usage: total-recall <command> [options]

package/src/cli/memory-init.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getGlobalAgentDir } from './agent-dir.mjs';
 import { registerProjectBrain, writeBrainIdentity, VAULT_CATEGORIES } from '../core/memory-brain.mjs';
+import { ensureRequiredPlugins } from '../core/required-plugins.mjs';
 
 export default async function init(args = []) {
   if (args.includes('--help') || args.includes('-h')) {
@@ -24,6 +25,7 @@ export default async function init(args = []) {
   for (const relative of ['config', 'plugins', 'memory-derived', ...VAULT_CATEGORIES.map(c => `memory-vault/${c}`)]) {
     fs.mkdirSync(path.join(brainDir, relative), { recursive: true });
   }
+  ensureRequiredPlugins(brainDir);
   const skillFile = path.join(brainDir, 'SKILL.md');
   if (!fs.existsSync(skillFile)) {
     // Resolve the template by PATH, not `new URL(..., import.meta.url)`. Under a

package/src/cli/plugin/index.mjs

@@ -25,6 +25,7 @@ Usage:
 Commands:
   list                      Installed plugins (project & global) with source and sharing
   library [--plugin ID]      Installed CLI operation library (--json for agents)
+  refresh                   Rebuild installed command inventories and instruction surfaces
   on <id> / off <id>         Enable/disable host execution; compile catalogs and surfaces
   available [query]         Plugins bundled with this Total Recall package
   peers [query]             Plugins your mesh peers share (queried live)
@@ -38,6 +39,7 @@ Commands:
                               <git-url>           a git repository with plugin.json
                               <path>              a local directory
                               --link, -l    Symlink a local directory instead of copying
+                              --replace     Replace an install, retain previous source and restore on failure
                               --global, -g  Install for every project on this machine
    share <id>                Offer an installed plugin by direct link and mesh
   unshare <id>              Stop offering it
@@ -83,6 +85,15 @@ export async function run(argv = []) {
 
   const command = args[0];
   const rest = args.slice(1);
+  if (command === 'refresh') {
+    const { recompileAfterPluginMutation } = await import('../../core/plugin-store.mjs');
+    const result = await recompileAfterPluginMutation(process.cwd(), rest.includes('--global'));
+    const { setupInstalledPlugins } = await import('../../core/plugin-setup.mjs');
+    const setup = result.ok ? await setupInstalledPlugins() : {ok:false,results:[]};
+    console.log(JSON.stringify({...result,setup,ok:result.ok && setup.ok}));
+    if (!result.ok || !setup.ok) process.exitCode = 1;
+    return;
+  }
   if (command === 'on' || command === 'off') {
     const result = await setPluginActive(rest[0], command === 'on');
     console.log(JSON.stringify(result));

package/src/cli/plugin/install.mjs

@@ -13,11 +13,12 @@ export async function installPlugin(args = []) {
   }
 
   try {
-    const result = await install(source, { projectRoot: process.cwd(), global: isGlobal, link: isLink });
+    const result = await install(source, { projectRoot: process.cwd(), global: isGlobal, link: isLink, replace:args.includes('--replace') });
     const from = result.source.kind === 'peer' ? `peer ${result.source.peer_hostname}` : result.source.kind;
     console.log(`\n✅ Installed '${result.plugin.name}' (id: ${result.plugin.id}, v${result.plugin.version}) from ${from}`);
     console.log(`   Location: ${result.plugin.dir}`);
     console.log(`   sha256:   ${result.sha256}`);
+    if(result.previousDirectory)console.log(`   Previous source retained: ${result.previousDirectory}`);
     if (result.dependencies?.installed) {
       console.log(`   Dependencies: installed ${result.dependencies.packages.length} package(s)`);
     } else if (result.dependencies?.reason && !['no package.json', 'no dependencies declared'].includes(result.dependencies.reason)) {

package/src/cli/rebuild.mjs

@@ -72,13 +72,14 @@ export async function runRebuild(options = {}) {
   if (fs.existsSync(derivedDir)) {
     for (const entry of fs.readdirSync(derivedDir)) {
       if (entry.startsWith('embeddings.db')) continue; // also skips -wal / -shm
+      if (entry === 'cli-semantic-index.json') continue;
       fs.rmSync(path.join(derivedDir, entry), { recursive: true, force: true });
     }
   }
 
   console.log('🏗️  Recompiling surface from canonical vault...');
   try {
-    const stats = await compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile, force: true });
+    const stats = await compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile, force: Boolean(options.force) });
     console.log(`✅ Processed ${stats.nodesProcessed} canonical memory nodes.`);
     console.log(`✅ Injected memory into ${stats.skillsInjected} skill files.`);
     console.log(`✅ Rebuilt graph-index.jsonl, memory-layers.jsonl, and skill-routes.jsonl.`);
@@ -163,6 +164,7 @@ export default async function cli(args) {
   const { layer, remainingArgs } = parseLayerFlag(args);
   const options = {
     check: remainingArgs.includes('--check'),
+    force: remainingArgs.includes('--force'),
     layer,
   };
   let code = await runRebuild(options);

package/src/cli/startup.mjs

@@ -35,7 +35,8 @@ export default async function startup(args = []) {
   const report = await inspectStartup(options);
   if (args.includes('--json')) console.log(JSON.stringify(report, null, 2));
   else {
-    console.log(`Startup: server ${report.server?.status || 'unknown'}; brain ${report.brain?.status || 'unknown'}; daemon ${report.daemon?.status || 'unknown'}; SSSS tooling ${report.ssss?.status || 'unknown'}; app ${report.app?.status || 'unknown'}`);
+    console.log(`Startup: required plugins ${report.required_plugins?.status || 'unknown'}; server ${report.server?.status || 'unknown'}; brain ${report.brain?.status || 'unknown'}; daemon ${report.daemon?.status || 'unknown'}; SSSS tooling ${report.ssss?.status || 'unknown'}; app ${report.app?.status || 'unknown'}`);
+    for (const error of report.required_plugins?.errors || []) console.log(`Required plugin: ${error}`);
     const harnesses = await queryHarnessUsage().catch(() => []);
     const availH = harnesses.filter(h => h.available);
     const readyH = availH.filter(h => h.authed);

package/src/cli/update.mjs

@@ -18,6 +18,7 @@ import {
 import { brainDir } from '../core/config.mjs';
 import { installAutoPull } from '../core/autopull-install.mjs';
 import { updateAllBrains } from '../core/brain-updates.mjs';
+import { automaticUpdateStatus, runAutomaticBrainUpdates } from '../core/automatic-brain-updates.mjs';
 
 /** @param {string[]} args */
 export function parseArgs(args) {
@@ -32,6 +33,9 @@ export function parseArgs(args) {
     noBuild: false,
     allBrains: false,
     json: false,
+    automatic: false,
+    status: false,
+    localOnly: false,
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -45,6 +49,9 @@ export function parseArgs(args) {
     else if (a === '--no-build') opts.noBuild = true;
     else if (a === '--all-brains') opts.allBrains = true;
     else if (a === '--json') opts.json = true;
+    else if (a === '--automatic') opts.automatic = true;
+    else if (a === '--status') opts.status = true;
+    else if (a === '--local-only') opts.localOnly = true;
   }
   return opts;
 }
@@ -64,6 +71,10 @@ function printHelp() {
     total-recall update --all-brains --apply [--json]
         Pin the same published versions, use npm/pnpm, replace shared dependency
         links with independent local installs, and verify every resolved version.
+    total-recall update --automatic [--json]
+        Daemon maintenance: update both packages, ensure defaults and refresh surfaces.
+    total-recall update --status [--json]
+        Read the actual last automatic maintenance report without starting work.
 
   This brain's own checkout (git):
     total-recall update --install-autopull [--port N] [--no-build] [--dry-run]
@@ -89,6 +100,14 @@ export default async function update(args = []) {
     return;
   }
 
+  if(opts.status){const status=automaticUpdateStatus(brainDir);console.log(JSON.stringify(status,null,2));return status;}
+  if(opts.automatic){
+    const report=await runAutomaticBrainUpdates({brainDir,force:opts.force,fleet:!opts.localOnly});
+    console.log(JSON.stringify(report,null,2));
+    if(report.failed)process.exitCode=1;
+    return report;
+  }
+
   if (opts.allBrains) {
     const summary = await updateAllBrains({ brainDir, roots: opts.repos,
       dryRun: !opts.apply || opts.dryRun });

package/src/core/automatic-brain-updates.mjs

@@ -0,0 +1,67 @@
+/** The existing TR daemon maintains both published brain packages, not only TR. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { updateAllBrains } from './brain-updates.mjs';
+import { isPackageAutoUpdateEnabled } from './package-auto-update.mjs';
+import { maintainCliSurfaces } from './cli-maintenance.mjs';
+import { runBounded, cliEntry } from './startup-health.mjs';
+import { logger } from './logger.mjs';
+import { readProcessCommand, shouldHonorPidLock } from './pid-lock.mjs';
+import { updateGlobalBrainPackages } from './global-brain-updates.mjs';
+import { updateMeshBrainPackages } from './mesh-brain-updates.mjs';
+import { updateSourceBrainPackages } from './source-brain-updates.mjs';
+
+export function automaticUpdateStatus(brainDir) {
+  let last;
+  try { last=JSON.parse(fs.readFileSync(path.join(brainDir,'memory-derived/automatic-brain-updates.json'),'utf8')); } catch {}
+  return {enabled:isPackageAutoUpdateEnabled(), intervalMs:60*60*1000, last:last || null};
+}
+
+// Keep synchronous package-manager work outside the daemon's event loop. This
+// timer runs even when the task queue is empty; it does not create a scheduler.
+export function startAutomaticBrainUpdates({brainDir,intervalMs=60*60*1000,run=runBounded,onError=message=>logger.error('automatic-brain-updates',message)}={}) {
+  let busy=false,stopped=false;
+  const tick=async()=>{
+    if(busy || stopped)return;
+    busy=true;
+    try {
+      const result=await run(process.execPath,[cliEntry,'update','--automatic','--json'],{cwd:path.resolve(brainDir,'../../..'),timeoutMs:55*60*1000,maxBytes:8*1024*1024});
+      if(result.code!==0)onError(result.reason || result.output || 'Automatic update failed');
+    } catch(error){onError(error.message);} finally{busy=false;}
+  };
+  // Wake frequently enough to retry failures; successful checks remain hourly.
+  const timer=setInterval(tick,Math.min(intervalMs,5*60*1000));timer.unref?.();void tick();
+  return {tick,stop(){stopped=true;clearInterval(timer);}};
+}
+
+export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false,skipThrottle=false,intervalMs=60*60*1000,update=updateAllBrains,compile=maintainCliSurfaces,globalUpdate=updateGlobalBrainPackages,meshUpdate=updateMeshBrainPackages,sourceUpdate=updateSourceBrainPackages,now=Date.now}={}) {
+  if(!force && !isPackageAutoUpdateEnabled())return {skipped:true,reason:'disabled',results:[]};
+  const file=path.join(brainDir,'memory-derived/automatic-brain-updates.json');
+  let saved;try{saved=JSON.parse(fs.readFileSync(file,'utf8'));}catch{}
+  const delay=saved?.failed?Math.min(intervalMs,5*60*1000):intervalMs;
+  if(!force && !skipThrottle && saved?.checkedAt && now()>=saved.checkedAt && now()-saved.checkedAt<delay)return {skipped:true,reason:'throttled',results:[]};
+  fs.mkdirSync(path.dirname(file),{recursive:true});
+  const lock=`${file}.lock`;
+  let fd;
+  if(fs.existsSync(lock)){
+    const text=fs.readFileSync(lock,'utf8');
+    const verdict=Number(text)===process.pid ? {honor:true} : shouldHonorPidLock(Number(text),{isAlive:pid=>{try{process.kill(pid,0);return true;}catch{return false;}},readCommand:readProcessCommand,entryHint:'total-recall'});
+    if(!verdict.honor && fs.readFileSync(lock,'utf8')===text)fs.unlinkSync(lock);
+  }
+  try {fd=fs.openSync(lock,'wx',0o600);fs.writeFileSync(fd,String(process.pid));}
+  catch(error){if(error.code==='EEXIST')return {skipped:true,reason:'maintenance-already-running',failed:1,results:[]};throw error;}
+  try {
+    let report;
+    try {
+      const summary=await update({brainDir,dryRun:false,ensureDefaults:true});
+      const global=summary.versions?await globalUpdate({versions:summary.versions}):{failed:1,results:[],error:'Cannot maintain global packages without verified published versions'};
+      const sources=summary.versions?await sourceUpdate({brainDir,versions:summary.versions}):{failed:1,results:[]};
+      const mesh=fleet && summary.versions?await meshUpdate({versions:summary.versions,version:summary.versions['total-recall-brain']}):{failed:0,results:[],scope:'local-only'};
+      const changed=summary.updated>0 || global.results.some(row=>row.status==='updated') || sources.results.some(row=>row.status==='updated') || JSON.stringify(saved?.versions)!==JSON.stringify(summary.versions);
+      const surfaces=await compile({brainDir,force:changed});
+      report={...summary,global,sources,mesh,surfaces,failed:(summary.failed || 0)+global.failed+sources.failed+mesh.failed+(surfaces.ok?0:surfaces.results.filter(row=>row.status==='failed').length),checkedAt:now()};
+    }catch(error){report={failed:1,error:error.message,checkedAt:now(),results:[]};}
+    const temporary=`${file}.${process.pid}.tmp`;fs.writeFileSync(temporary,JSON.stringify(report,null,2));fs.renameSync(temporary,file);
+    return report;
+  } finally {fs.closeSync(fd);fs.unlinkSync(lock);}
+}

package/src/core/brain-updates.mjs

@@ -8,11 +8,14 @@ import { createHash } from 'node:crypto';
 import { listUpdateRoots, resolveRegistryFiles, readRegistryEntries, rootsFromEnv } from './package-auto-update.mjs';
 import { discoverPlugins } from './plugin-loader.mjs';
 import { comparePackageVersions } from './package-version.mjs';
+import { inspectRequiredPlugins } from './required-plugins.mjs';
+import { ensureRequiredPlugins } from './required-plugins.mjs';
+import YAML from 'yaml';
 
 export const BRAIN_PACKAGES = ['total-recall-brain', '@gregiteen/ssss-cli'];
 const sections = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
 const ignored = new Set(['node_modules', 'vendor', 'dist', 'build', 'coverage', 'venv',
-  'test', 'tests', '__tests__', 'fixtures', 'tmp', 'scratch']);
+  'test', 'tests', '__tests__', 'fixtures', 'tmp', 'scratch', 'scaffold']);
 const canonical = key => key === '@ssss/cli' ? '@gregiteen/ssss-cli' : key;
 const read = file => JSON.parse(fs.readFileSync(file, 'utf8'));
 const isLink = file => { try { return fs.lstatSync(file).isSymbolicLink(); } catch { return false; } };
@@ -68,7 +71,12 @@ export function brainInstallOwner(root) {
     const file = path.join(dir, 'package.json');
     if (fs.existsSync(file)) {
       const pkg = read(file);
-      if (dir === root || pkg.workspaces || fs.existsSync(path.join(dir, 'pnpm-workspace.yaml'))) owner = dir;
+      let patterns=Array.isArray(pkg.workspaces)?pkg.workspaces:pkg.workspaces?.packages || [];
+      const pnpm=path.join(dir,'pnpm-workspace.yaml');
+      if(fs.existsSync(pnpm))patterns=[...patterns,...(YAML.parse(fs.readFileSync(pnpm,'utf8'))?.packages || [])];
+      const relative=path.relative(dir,root).split(path.sep).join('/');
+      const belongs=patterns.some(pattern=>typeof pattern==='string' && !pattern.startsWith('!') && new RegExp('^'+pattern.split('/').map(part=>part==='**'?'.*':part.split('*').map(chunk=>chunk.replace(/[.*+?^${}()|[\]\\]/g,'\\$&')).join('[^/]*')).join('/')+'$').test(relative));
+      if (dir === root || belongs) owner = dir;
     }
     if (dir === path.dirname(dir)) break;
   }
@@ -90,6 +98,17 @@ export async function updateAllBrains(opts = {}) {
   const exec = opts.exec || spawnSync;
   const roots = listUpdateRoots(opts).map(row => row.root);
   const errors = [];
+  const brains = roots.map(root => ({ root, brain: path.join(root, '.agent', 'skills', 'total-recall') }))
+    .filter(({ brain }) => fs.existsSync(brain));
+  if (opts.brainDir) brains.push({ root: opts.brainDir, brain: opts.brainDir });
+  for (const { root, brain } of brains) {
+    if (!dryRun && opts.ensureDefaults === true) {
+      try { ensureRequiredPlugins(brain); }
+      catch(error){errors.push({root,status:'failed',error:error.message});continue;}
+    }
+    const required = inspectRequiredPlugins(brain);
+    if (required.status !== 'ready') errors.push({ root, status: 'failed', error: required.errors.join('; ') });
+  }
   const requested = [...(opts.roots || []), ...rootsFromEnv(),
     ...resolveRegistryFiles(opts).flatMap(file => readRegistryEntries(file).map(row => row.path)).filter(Boolean)];
   for (const root of new Set(requested.map(root => path.resolve(root)))) {

package/src/core/cli-commands.mjs

@@ -0,0 +1,71 @@
+/** Canonical built-in CLI routing inventory. */
+export const CLI_COMMANDS = {
+  app:      'app/index.mjs',
+  init:     'init.mjs',
+  setup:    'setup.mjs',
+  start:    'start.mjs',
+  startup:  'startup.mjs',
+  deploy:   'deploy.mjs',
+  doctor:   'doctor.mjs',
+  backup:   'backup.mjs',
+  dream:    'dream.mjs',
+  lint:     'lint.mjs',
+  daemon:   'daemon.mjs',
+  restore:  'restore.mjs',
+  upgrade:  'upgrade.mjs',
+  update:   'update.mjs',
+  friction: 'friction.mjs',
+  chat:     'chat.mjs',
+  status:   'status.mjs',
+  remember: 'remember.mjs',
+  forget:   'forget.mjs',
+  edit:     'edit.mjs',
+  recall:   'recall.mjs',
+  context:  'context.mjs',
+  rules:    'rules.mjs',
+  search:   'recall.mjs',
+  research: 'research.mjs',
+  proposals: 'proposals.mjs',
+  proposal:  'proposals.mjs',
+  task:     'task.mjs',
+  share:    'share.mjs',
+  'generate-pat': 'generate-pat.mjs',
+  key:      'key.mjs',
+  keys:     'key.mjs',
+  pat:      'key.mjs',
+  'hash-password': 'hash-password.mjs',
+  'reset-password': 'reset-password.mjs',
+  compile:  'rebuild.mjs',
+  rebuild:  'rebuild.mjs',
+  snapshot: 'snapshot.mjs',
+  migrate:  'migrate.mjs',
+  backfill: 'backfill.mjs',
+  ingest:   'ingest.mjs',
+  import:   'import-rules.mjs',
+  connect:  'connect.mjs',
+  sync:     'sync.mjs',
+  relay:    'relay.mjs',
+  uninstall: 'uninstall.mjs',
+  map:      'map.mjs',
+  brain:    'brain.mjs',
+  config:   'config.mjs',
+  skill:    'skill.mjs',
+  'project-id': 'project-id.mjs',
+  api:      'api.mjs',
+  brief:    'brief.mjs',
+  group:    'group.mjs',
+  groups:   'group.mjs',
+  help:     'help.mjs',
+  collab:   'collab.mjs',
+  command:  'command.mjs',
+  export:   'export.mjs',
+  harness:  'harness.mjs',
+  watch:    'rebuild.mjs',
+  agent:    'agent.mjs',
+  agents:   'agent.mjs',
+  new:      'new.mjs',
+  plugin:   'plugin/index.mjs',
+  plugins:  'plugin/index.mjs',
+  scaffold: 'plugin/scaffold-cmd.mjs',
+  'scaffold-plugin': 'plugin/scaffold-cmd.mjs',
+};

package/src/core/cli-maintenance.mjs

@@ -0,0 +1,45 @@
+/** Daemon-owned change detection for CLI inventories and every registered surface. */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { listLocalBrains } from './brain-registry.mjs';
+import { buildPluginCatalog } from './plugin-catalog.mjs';
+import { discoverPlugins, PACKAGE_ROOT } from './plugin-loader.mjs';
+import { runBounded } from './startup-health.mjs';
+import { logger } from './logger.mjs';
+
+export function cliInputFingerprint(root) {
+  const hash=crypto.createHash('sha256');
+  const add=file=>{try{const stat=fs.statSync(file);hash.update(`${file}:${stat.mtimeMs}:${stat.size}\n`);}catch{hash.update(`missing:${file}\n`);}};
+  for(const file of ['bin/total-recall.mjs','src/core/cli-commands.mjs','src/core/cli-quick-reference.mjs'])add(path.join(PACKAGE_ROOT,file));
+  const walk=directory=>{for(const item of fs.readdirSync(directory,{withFileTypes:true})){const file=path.join(directory,item.name);if(item.isDirectory())walk(file);else if(item.name.endsWith('.mjs'))add(file);}};
+  walk(path.join(PACKAGE_ROOT,'src/cli'));
+  hash.update(buildPluginCatalog(root).fingerprint);
+  for(const plugin of discoverPlugins(root)){add(plugin.manifestPath);if(plugin.manifest.cli?.handler)add(path.join(plugin.dir,plugin.manifest.cli.handler));}
+  return hash.digest('hex');
+}
+
+export async function maintainCliSurfaces({brainDir,brains,force=false,run=runBounded,fingerprint=cliInputFingerprint}={}) {
+  const results=[];
+  for(const brain of brains || listLocalBrains({globalBrainDir:brainDir})) {
+    if(!brain.exists || brain.enabled===false)continue;
+    const root=brain.root || path.dirname(path.dirname(brain.brainDir));
+    const file=path.join(brain.brainDir,'memory-derived/cli-maintenance.json');
+    let previous;try{previous=JSON.parse(fs.readFileSync(file,'utf8'));}catch{}
+    const current=fingerprint(root);
+    if(!force && previous?.fingerprint===current){results.push({root,status:'current'});continue;}
+    const result=await run(process.execPath,[path.join(PACKAGE_ROOT,'bin/total-recall.mjs'),'plugin','refresh',...(brain.kind==='global'?['--global']:[])],{cwd:root,timeoutMs:600000,maxBytes:262144});
+    if(result.code!==0){results.push({root,status:'failed',error:result.reason || result.output?.slice(-1000) || 'CLI compilation failed'});continue;}
+    fs.mkdirSync(path.dirname(file),{recursive:true});
+    const temp=`${file}.${process.pid}.tmp`;fs.writeFileSync(temp,JSON.stringify({fingerprint:current,compiledAt:new Date().toISOString()}));fs.renameSync(temp,file);
+    results.push({root,status:'refreshed'});
+  }
+  return {ok:results.every(row=>row.status!=='failed'),results};
+}
+
+export function startCliSurfaceMaintenance({brainDir,intervalMs=30000}={}) {
+  let busy=false;
+  const tick=async()=>{if(busy)return;busy=true;try{const result=await maintainCliSurfaces({brainDir});if(!result.ok)logger.error('cli-maintenance',JSON.stringify(result));}catch(error){logger.error('cli-maintenance',error.message);}finally{busy=false;}};
+  const timer=setInterval(tick,intervalMs);timer.unref?.();void tick();
+  return {stop(){clearInterval(timer);}};
+}

package/src/core/cli-quick-reference.mjs

@@ -0,0 +1,20 @@
+/**
+ * The command map every compiled instruction surface leads with, so an agent
+ * sees which CLI owns a job before it reaches for curl, sed or ssh. The plugin
+ * namespaces and their operations are appended live by
+ * `buildInstalledPluginsSummary`, so they cannot go stale.
+ * `cli-quick-reference.spec.mjs` fails when a listed command stops existing in
+ * `total-recall --help`.
+ */
+import { CLI_COMMANDS } from './cli-commands.mjs';
+export const CLI_QUICK_REFERENCE_COMMANDS = Object.keys(CLI_COMMANDS);
+
+export const CLI_QUICK_REFERENCE = `## TOTAL RECALL CLI — USE IT FOR EVERYTHING (run \`total-recall <command> --help\` before guessing)
+- Built-in commands: ${CLI_QUICK_REFERENCE_COMMANDS.map(command => `\`${command}\``).join(' · ')}
+- Memory: \`context "<task>" --action <a>\` · \`recall "<q>" --local\` · \`remember <category> "<text>" --global|--project\` · \`edit <slug>\` · \`compile\` · \`brief\` · \`status\` / \`doctor\`
+- CREDENTIALS GO THROUGH THE AUTH PLUGIN ONLY (Total Recall has no native secrets store; never hand-roll curl/sed/ssh for keys): \`auth secret list|get <K>|set <K> --stdin|rotate <K> --stdin|--from-clipboard [--remote <t>]|rotate-auto <K>|rotation-due|shared|meta|catalog|audit|diff-env|export-env\`; remote targets: \`auth secret remote add|list|deploy <t> [--keys a,b] [--dry-run]\`. The store follows \`TR_SECRETS_BRAIN\`.
+- Auth: \`auth status|audit|key list|issue|revoke|password set --stdin|passkey|google status\`
+- Mesh nodes: \`mesh nodes|status|ping|exec <node> <cmd>|ssh <node> [cmd]|access <node>|leader\` — never ssh a machine into itself.
+- Agents and work: \`agent spawn|list|logs|kill\` · \`harness dispatch|council\` · \`task <cmd>\` · \`plugin list|install|info|library\` · \`skill <cmd>\` · \`brain <cmd>\` · \`daemon <cmd>\` · \`update --all-brains --apply\`
+- Every installed plugin namespace and its operations is listed next; run \`total-recall <namespace> --help\` for flags.
+`;