total-recall-brain 3.40.0 → 3.40.2

package/src/cli/brief.mjs

@@ -14,7 +14,10 @@ const argl = Array.isArray(args) ? args : [];
 const asJson = argl.includes('--json');
 const withMesh = argl.includes('--mesh');
 if (argl.includes('--help') || argl.includes('-h')) {
-  console.log(`Usage: total-recall brief [--json] [--mesh]
+  console.log(`Usage: total-recall brief [--json] [--mesh] [--all-projects]
+
+--all-projects inventories outstanding trackers and daemon tasks across every
+registered root, with source paths and dates; it does not claim live readiness.
 
 Read-only brief for the start of a session in the current repo. Composes:
 project-id, group, command list, secret catalog/rotation-due/shared/tracking-health
@@ -23,6 +26,27 @@ the compiled rules line, docs/projects trackers, openwiki, and the repo's own
 .agent/skills/start/SKILL.md, which you follow next when it exists.`);
   return;
 }
+if(argl.includes('--all-projects')){
+  const {outstandingProjectStatus,formatOutstandingProjectStatus}=await import('../core/project-status.mjs');
+  const report=outstandingProjectStatus();
+  if(argl.includes('--output')){
+    const at=argl.indexOf('--output');if(!argl[at+1] || argl[at+1].startsWith('--'))throw new Error('--output requires a file path');
+    const output=path.resolve(argl[at+1]);fs.mkdirSync(path.dirname(output),{recursive:true,mode:0o700});
+    fs.writeFileSync(output,output.endsWith('.json')?JSON.stringify(report,null,2):formatOutstandingProjectStatus(report),{mode:0o600});
+    console.log(JSON.stringify({output,rootCount:report.rootCount,projectCount:report.projectCount,taskCount:report.tasks.length}));return report;
+  }
+  if(argl.includes('--summary')){
+    console.log(JSON.stringify({generatedAt:report.generatedAt,rootCount:report.rootCount,projectCount:report.projectCount,openCheckboxCount:report.openCheckboxCount,evidence:report.evidence,projects:report.projects.filter(row=>row.projects.length).map(row=>({name:row.name,projects:row.projects.map(p=>({id:p.id,state:p.state,status:p.status,open:p.openCount,modifiedAt:p.modifiedAt}))})),tasks:report.tasks.reduce((counts,task)=>{const key=task.slug==='onboarding-interview'?'onboarding-template':`${task.status}:${task.executor}`;counts[key]=(counts[key] || 0)+1;return counts;},{}),missing:report.missing},null,2));return report;
+  }
+  if(asJson)console.log(JSON.stringify(report,null,2));
+  else {
+    console.log(`${report.rootCount} roots; ${report.projectCount} outstanding project trackers; ${report.openCheckboxCount} unchecked items; ${report.tasks.length} outstanding daemon tasks.\n${report.evidence}`);
+    for(const repo of report.projects.filter(row=>row.projects.length))for(const project of repo.projects)console.log(`${repo.name} / ${project.id}: ${project.state}, ${project.status}, ${project.openCount ?? '?'} open — ${project.tracker || project.folder}`);
+    for(const task of report.tasks)console.log(`Task ${task.slug}: ${task.status} — ${task.intent}`);
+    for(const row of report.missing)console.log(`Missing root: ${row.root}`);
+  }
+  return report;
+}
 
 // Run a Total Recall verb (async, bounded). Output is parsed for counts only.
 const tr = (verbArgs, ms = 45000) => new Promise((resolve) => {
@@ -51,12 +75,12 @@ const [pid, groupsRes, cmds, catalog, due, shared, tracking, tasks, secretList,
   tr(['project-id', '--json']),
   tr(['group', 'list', '--json']),
   tr(['command', 'list', '--json']),
-  tr(['secret', 'catalog']),
-  tr(['secret', 'rotation-due']),
-  tr(['secret', 'shared']),
-  tr(['secret', 'tracking-health']),
+  tr(['auth', 'secret', 'catalog']),
+  tr(['auth', 'secret', 'rotation-due']),
+  tr(['auth', 'secret', 'shared']),
+  tr(['auth', 'secret', 'tracking-health']),
   tr(['task', 'list']),
-  tr(['secret', 'list']),
+  tr(['auth', 'secret', 'list']),
   tr(['mesh', 'status', '--json']),
   withMesh ? tr(['mesh', 'ping', '--json'], 60000) : Promise.resolve(null),
 ]);
@@ -154,9 +178,9 @@ const harnesses = await queryHarnessUsage().catch(() => []);
 const warnings = [];
 if (!runtime.ready) warnings.push('Shared runtime readiness failed or unknown: total-recall startup check --json.');
 if (!project?.project_id) warnings.push('No project brain here (total-recall init) — memory, secrets and rules are global-only.');
-if (secrets.rotation_due && secrets.rotation_due !== 0) warnings.push(`Secrets overdue for rotation: ${secrets.rotation_due} (total-recall secret rotation-due).`);
-if (secrets.shared_values && secrets.shared_values !== 0) warnings.push(`Credential values reused across keys/apps: ${secrets.shared_values} group(s) (total-recall secret shared).`);
-if (secrets.untracked && secrets.untracked !== 0) warnings.push(`Secrets without usage/account tracking: ${secrets.untracked} (total-recall secret tracking-health).`);
+if (secrets.rotation_due && secrets.rotation_due !== 0) warnings.push(`Secrets overdue for rotation: ${secrets.rotation_due} (total-recall auth secret rotation-due).`);
+if (secrets.shared_values && secrets.shared_values !== 0) warnings.push(`Credential values reused across keys/apps: ${secrets.shared_values} group(s) (total-recall auth secret shared).`);
+if (secrets.untracked && secrets.untracked !== 0) warnings.push(`Secrets without usage/account tracking: ${secrets.untracked} (total-recall auth secret tracking-health).`);
 if (rules && (now - new Date(rules.compiled)) > 7 * 86400000) warnings.push(`Instruction surfaces last compiled ${rules.compiled.slice(0, 10)} — run total-recall compile.`);
 for (const w of openwiki) if (w.updated && (now - new Date(w.updated)) > 30 * 86400000) warnings.push(`OpenWiki ${w.dir} last updated ${w.updated.slice(0, 10)} — may be stale.`);
 if (meshStatus && meshStatus.configured === false) warnings.push(`Mesh not configured: ${meshStatus.reason || 'unknown'}.`);

package/src/cli/command.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { spawn } from 'node:child_process';
 import { resolveBrainLayer } from '../core/config.mjs';
 import { isSafeRelativePath, validatePluginManifest } from '../core/plugin-loader.mjs';
+import { CLI_COMMANDS } from '../core/cli-commands.mjs';
 
 const COMMAND_NAME = /^[a-z][a-z0-9-]{0,63}$/;
 
@@ -204,13 +205,7 @@ export async function run(argv = []) {
  * dispatcher itself so this list cannot drift.
  */
 export function builtinCommandNames() {
-  try {
-    const bin = fs.readFileSync(new URL('../../bin/total-recall.mjs', import.meta.url), 'utf8');
-    const block = bin.match(/^const COMMANDS = \{([\s\S]*?)^\};/m)?.[1] || '';
-    return new Set([...block.matchAll(/^\s+'?([a-z][a-z0-9-]*)'?\s*:/gm)].map((m) => m[1]));
-  } catch {
-    return new Set();
-  }
+  return new Set(Object.keys(CLI_COMMANDS));
 }
 
 const RISKS = new Set(['read', 'write', 'money', 'dns-cert', 'production-deploy', 'secret-revoke']);

package/src/cli/config.mjs

@@ -30,6 +30,7 @@ const KEY_MAP = {
   // default when every rule should load for every action instead of being
   // narrowed by applicability.
   'context_budget': { file: 'surface', path: 'context.budget', type: 'number' },
+  'surface_bootstrap_budget': { file: 'surface', path: 'budget.bootstrap_total_tokens', type: 'number' },
 };
 
 function resolveKeyInfo(key) {

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',
+};