total-recall-brain 3.40.1 → 3.40.2

package/src/core/context-compiler.mjs

@@ -93,7 +93,33 @@ export async function compileContext({
   }).filter(candidate => candidate.relevant).sort((a, b) => b.score - a.score);
   const optional = candidates.map(({ node: n }) => ({ id: `${n._layer || 'project'}:${n.slug}`,
     text: `## ${n.title || n.slug} [${n.slug}]\n\n${(n.body || n.content || '').trim()}` }));
-  const result = assembleContext([...required, ...optional, ...contributions], { total: b.total });
+
+  // CLI Semantic Index recommendations: top task-matched runnable CLI verbs
+  let cliVerbContribution = null;
+  if (query && String(query).trim()) {
+    try {
+      const { queryCliSemanticIndex } = await import('./cli-semantic-index.mjs');
+      const matchedVerbs = await queryCliSemanticIndex(query, {
+        derivedDir,
+        projectRoot,
+        limit: 5,
+        minScore: 0.35,
+      });
+      if (matchedVerbs.length > 0) {
+        const verbLines = matchedVerbs.map(v => `- \`${v.usage || v.verb}\` — ${v.description}`);
+        cliVerbContribution = {
+          id: 'cli:recommended-verbs',
+          required: false,
+          text: `### Recommended Task Verbs\n\n${verbLines.join('\n')}`,
+        };
+      }
+    } catch {
+      /* non-fatal */
+    }
+  }
+
+  const cliContributions = cliVerbContribution ? [cliVerbContribution] : [];
+  const result = assembleContext([...required, ...cliContributions, ...optional, ...contributions], { total: b.total });
   result.stats.total_nodes = allNodes.length;
   result.stats.compile_ms = Date.now() - startTime;
   result.stats.consumer = consumer;

package/src/core/crons.mjs

@@ -3,7 +3,6 @@ import { logger } from './logger.mjs';
 import { runGitHubSync, getGitHubSyncStatus } from './github-sync.mjs';
 import { watchObsidianDirectory } from './obsidian-sync.mjs';
 const { getSecret } = await __loadOwnedPlugin('auth', 'secrets-store');
-import { runPackageAutoUpdate } from './package-auto-update.mjs';
 
 /**
  * runCrons — scheduled background jobs.
@@ -30,18 +29,8 @@ export async function runCrons(options) {
       // Obsidian not configured
     }
 
-    // 3. npm package auto-update for registered projects (total-recall-brain)
-    try {
-      const pkg = await runPackageAutoUpdate({ brainDir });
-      if (!pkg.skipped && (pkg.updated > 0 || pkg.failed > 0)) {
-        logger.info({
-          subsystem: 'cron',
-          message: `package-auto-update: latest=${pkg.latest} updated=${pkg.updated} failed=${pkg.failed}`,
-        });
-      }
-    } catch (err) {
-      logger.warn({ subsystem: 'cron', message: `package-auto-update failed: ${err.message}` });
-    }
+    // Package maintenance has its own wall-clock timer in this same daemon.
+    // Task-count driven crons must never block the queue on npm installation.
   } catch (err) {
     logger.error({ subsystem: 'cron', message: `Cron execution failed: ${err.message}` });
   }

package/src/core/daemon-control.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { logger } from './logger.mjs';
 import { agentDir, brainDir } from './config.mjs';
+import { readProcessCommand } from './pid-lock.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, '..', '..');
@@ -29,6 +30,9 @@ export function readPid() {
     // Check if the process is alive using signal 0
     try {
       process.kill(pid, 0);
+      const command=readProcessCommand(pid);
+      if(!command)throw new Error('Cannot verify daemon process identity');
+      if(!command.includes(path.join('core','daemon-loop.mjs')) && !command.includes(path.join('core','dream.mjs')))return null;
       return pid;
     } catch {
       return null;
@@ -130,10 +134,8 @@ export function startDaemon() {
 export async function stopDaemon({ graceMs = 35_000, pollMs = 250 } = {}) {
   const pid = readPid();
   if (!pid) {
-    // Clear PID file in case it was a stale/dead record
-    try {
-      if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE);
-    } catch {}
+    // Startup owns stale-lock recovery. A live process with unreadable identity
+    // is not ours to signal or unlink.
     return false;
   }
 

package/src/core/daemon-loop.mjs

@@ -258,6 +258,8 @@ import { releaseLease } from './leader-election.mjs';
  * even a wedged iteration cannot keep the daemon alive indefinitely.
  */
 let stopPluginTasks = null;
+let stopCliMaintenance = null;
+let stopAutomaticUpdates = null;
 
 function shutdown(signal) {
   if (shuttingDown) return;
@@ -266,6 +268,8 @@ function shutdown(signal) {
   running = false;
   if (vaultWatcher) vaultWatcher.stop();
   if (stopPluginTasks) stopPluginTasks();
+  stopCliMaintenance?.();
+  stopAutomaticUpdates?.();
 
   const fallback = setTimeout(() => {
     logger.info({
@@ -328,6 +332,11 @@ async function main() {
   }
 
   // Start source watcher (auto-regenerates repo-expert on code changes)
+  try {
+    const { startCliSurfaceMaintenance } = await import('./cli-maintenance.mjs');
+    const maintenance=startCliSurfaceMaintenance({brainDir:BRAIN_DIR});
+    stopCliMaintenance=()=>maintenance.stop();
+  } catch(error) { logger.error('daemon-loop', `CLI surface maintenance failed: ${error.message}`); }
   try {
     const { detectProjectBrain } = await import('./config.mjs');
     const project = detectProjectBrain();
@@ -388,14 +397,9 @@ async function main() {
 
   // npm total-recall-brain auto-update for registered projects (throttled thereafter via crons)
   try {
-    const { runPackageAutoUpdate } = await import('./package-auto-update.mjs');
-    const pkg = await runPackageAutoUpdate({ brainDir: BRAIN_DIR, skipThrottle: true });
-    if (!pkg.skipped) {
-      logger.info({
-        subsystem: 'daemon-loop',
-        message: `Boot package-auto-update: latest=${pkg.latest} updated=${pkg.updated || 0} failed=${pkg.failed || 0}`,
-      });
-    }
+    const { startAutomaticBrainUpdates } = await import('./automatic-brain-updates.mjs');
+    const maintenance=startAutomaticBrainUpdates({brainDir:BRAIN_DIR});
+    stopAutomaticUpdates=()=>maintenance.stop();
   } catch (err) {
     logger.info({ subsystem: 'daemon-loop', message: `Boot package-auto-update failed: ${err.message}` });
   }

package/src/core/default-plugins.mjs

@@ -0,0 +1,5 @@
+/** Default runtime foundation and routine agent-development tools. */
+export const DEFAULT_PLUGIN_IDS = Object.freeze([
+  'auth', 'mesh', 'openwiki', 'composable-cli', 'cli-agents',
+  'code-quality', 'security', 'embeddings', 'git-sentinel',
+]);

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

@@ -0,0 +1,39 @@
+/** Verify and maintain globally installed CLIs without replacing a source checkout. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {BRAIN_PACKAGES} from './brain-updates.mjs';
+import {comparePackageVersions} from './package-version.mjs';
+import {updateSourceBrainPackage} from './source-brain-updates.mjs';
+
+export function updateGlobalBrainPackages({versions,exec=spawnSync,sourceUpdate=updateSourceBrainPackage}={}) {
+  const prefix=exec('npm',['root','--global'],{encoding:'utf8',timeout:15000});
+  if(prefix.status!==0)return {failed:1,results:[{status:'failed',error:'Cannot resolve global npm root'}]};
+  const root=prefix.stdout.trim();
+  const results=[];
+  const install=[];
+  for(const name of BRAIN_PACKAGES){
+    const directory=path.join(root,name),file=path.join(directory,'package.json');
+    let installed;try{installed=JSON.parse(fs.readFileSync(file,'utf8')).version;}catch{}
+    const row={package:name,installed:installed || null,latest:versions[name],status:'up_to_date'};results.push(row);
+    if(installed===versions[name])continue;
+    if(!versions[name]){row.status='failed';row.error='Published version is unavailable';continue;}
+    if(installed && comparePackageVersions(installed,versions[name])===1){row.status='failed';row.error='Newer local/preview global package; refusing implicit downgrade';continue;}
+    if(fs.existsSync(path.join(directory,'.git'))){
+      const result=sourceUpdate({directory:fs.realpathSync(directory),name,version:versions[name],exec});
+      row.status=result.ok?'updated':'failed';row.source=true;
+      if(result.ok){row.installed=result.installed;row.commit=result.commit;}else row.error=`Source checkout update failed: ${result.error}`;
+      continue;
+    }
+    row.status='pending';install.push(`${name}@${versions[name]}`);
+  }
+  if(install.length){
+    const result=exec('npm',['install','--global','--no-audit','--no-fund',...install],{encoding:'utf8',timeout:600000,maxBuffer:8*1024*1024});
+    for(const row of results.filter(row=>row.status==='pending')){
+      try{row.installed=JSON.parse(fs.readFileSync(path.join(root,row.package,'package.json'),'utf8')).version;}catch{}
+      row.status=result.status===0 && row.installed===row.latest?'updated':'failed';
+      if(row.status==='failed')row.error=result.error?.message || result.stderr?.slice(-1000) || 'Global version verification failed';
+    }
+  }
+  return {failed:results.filter(row=>row.status==='failed').length,results};
+}

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

@@ -0,0 +1,30 @@
+/** The daemon dispatches maintenance through the mesh owner; remote brains stay separate. */
+export async function updateMeshBrainPackages({version,versions,listNodes,exec,now=Date.now}={}) {
+  if(!/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(version || ''))throw new Error('A verified published TR version is required');
+  if(!listNodes || !exec){
+    const mesh=await import('./mesh.mjs');
+    listNodes ||= ()=>mesh.listEnrichedMeshNodes();
+    exec ||= mesh.execMeshCommand;
+  }
+  const results=[];
+  for(const node of await listNodes()){
+    if(node.self || !node.ip || !node.access?.ssh_user)continue;
+    const row={node:node.ip,status:'pending'};results.push(row);
+    if(!node.online){row.status='failed';row.error='Configured mesh node is offline; retry pending';continue;}
+    try{
+      // Read the durable report first, then launch only when stale or failed.
+      const observed=await exec(node.ip,'cd "$HOME" && total-recall update --status --json',{timeoutMs:20000});
+      let report;try{report=JSON.parse(observed.stdout).last;}catch{}
+      const current=observed.success && report && !report.failed && now()>=report.checkedAt && now()-report.checkedAt<2*60*60*1000 && report.versions?.['total-recall-brain']===version && (!versions?.['@gregiteen/ssss-cli'] || report.versions?.['@gregiteen/ssss-cli']===versions['@gregiteen/ssss-cli']);
+      if(current){row.status='verified';row.report=report;continue;}
+      // npm exec pins the verified release so an old installed CLI can bootstrap
+      // this capability. The remote command owns its lock, verification and report.
+      const command=`cd "$HOME" && nohup npm exec --yes --package=total-recall-brain@${version} -- total-recall update --automatic --local-only --json </dev/null >/tmp/total-recall-automatic-update.log 2>&1 &`;
+      const launched=await exec(node.ip,command,{timeoutMs:20000});
+      row.status=launched.success?'dispatched':'failed';
+      row.error=launched.success?'Awaiting independently verified remote report':launched.stderr || 'Mesh maintenance dispatch failed';
+    }catch(error){row.status='failed';row.error=error.message;}
+  }
+  // A dispatched process is not a verified update. Keep it visible for retries.
+  return {failed:results.filter(row=>row.status!=='verified').length,results};
+}

package/src/core/meta-harness.mjs

@@ -75,6 +75,33 @@ export const HARNESS_SPECS = {
     defaultFlags: ['-p'],
     execType: 'flag_last',
     description: 'Autonomous coding, repo analysis, and shell execution via xAI Grok.'
+  },
+  hermes: {
+    id: 'hermes',
+    name: 'Hermes Agent Runtime',
+    binary: 'hermes',
+    category: 'autonomous_agent',
+    defaultFlags: ['chat', '-p'],
+    execType: 'flag_last',
+    description: 'Supervised messaging gateway and multi-channel autonomous agent runtime.'
+  },
+  dsh: {
+    id: 'dsh',
+    name: 'DeepSeek Harness (DSH)',
+    binary: 'dsh',
+    category: 'reasoning_engine',
+    defaultFlags: ['-p'],
+    execType: 'flag_last',
+    description: 'High-throughput DeepSeek reasoning and tool execution harness.'
+  },
+  openclaw: {
+    id: 'openclaw',
+    name: 'OpenClaw Messaging Bridge',
+    binary: 'openclaw',
+    category: 'multichannel_bridge',
+    defaultFlags: ['status', '--json'],
+    execType: 'flag_last',
+    description: 'Multi-channel messaging bridge (WhatsApp, Telegram, Discord, Slack) and agent execution.'
   }
 };
 
@@ -227,6 +254,27 @@ export async function detectHarnessesWithAuth({ readSecret = readStoreSecret } =
         h.authed = true;
         h.authRoute = 'cached-google-signin';
       }
+    } else if (h.id === 'hermes') {
+      if (process.env.HERMES_API_KEY) {
+        h.authed = true;
+        h.authRoute = 'env-api-key';
+      } else if (fs.existsSync(path.join(os.homedir(), '.hermes')) || fs.existsSync(path.join(os.homedir(), '.agent', 'skills', 'total-recall', 'plugins', 'hermes'))) {
+        h.authed = true;
+        h.authRoute = 'cached-profile';
+      }
+    } else if (h.id === 'dsh') {
+      if (process.env.OPENROUTER_API_KEY) {
+        h.authed = true;
+        h.authRoute = 'env-api-key';
+      } else if (fs.existsSync(path.join(os.homedir(), '.dsh')) || fs.existsSync(path.join(os.homedir(), '.agent', 'skills', 'total-recall', 'plugins', 'dsh'))) {
+        h.authed = true;
+        h.authRoute = 'cached-dsh-config';
+      }
+    } else if (h.id === 'openclaw') {
+      if (fs.existsSync(path.join(os.homedir(), '.openclaw', 'openclaw.json'))) {
+        h.authed = true;
+        h.authRoute = 'cached-openclaw-config';
+      }
     }
   }
   return harnesses;
@@ -452,6 +500,25 @@ export function getInstalledHarnessVersion(harnessId) {
       const res = spawnSync('gemini', ['--version'], { timeout: 800, encoding: 'utf8' });
       const m = (res.stdout || '').match(/(\d+\.\d+\.\d+)/);
       if (m) return m[1];
+    } else if (harnessId === 'hermes') {
+      const res = spawnSync('hermes', ['--version'], { timeout: 1500, encoding: 'utf8' });
+      const m = (res.stdout || '').match(/(\d+\.\d+\.\d+)/);
+      if (m) return m[1];
+    } else if (harnessId === 'dsh') {
+      const res = spawnSync('dsh', ['--version'], { timeout: 1500, encoding: 'utf8' });
+      const m = (res.stdout || '').match(/(\d+\.\d+\.\d+)/);
+      if (m) return m[1];
+    } else if (harnessId === 'openclaw') {
+      const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+      if (fs.existsSync(configPath)) {
+        try {
+          const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+          if (cfg?.meta?.lastTouchedVersion) return cfg.meta.lastTouchedVersion;
+        } catch {}
+      }
+      const res = spawnSync('openclaw', ['--version'], { timeout: 1500, encoding: 'utf8' });
+      const m = (res.stdout || '').match(/(\d+\.\d+\.\d+)/);
+      if (m) return m[1];
     }
   } catch {}
   return 'unknown';
@@ -490,6 +557,12 @@ export async function getLatestHarnessVersion(harnessId, installedVersion = 'unk
       latest = '0.24.0';
     } else if (harnessId === 'gemini') {
       latest = '0.3.0';
+    } else if (harnessId === 'hermes') {
+      latest = '0.1.0';
+    } else if (harnessId === 'dsh') {
+      latest = '1.1.1';
+    } else if (harnessId === 'openclaw') {
+      latest = '2026.4.10';
     }
   } catch {}
 
@@ -640,6 +713,41 @@ export async function queryHarnessUsage() {
       rolling5hRemainingPct = '100% (unlimited)';
       weeklyRemainingPct = '100% (unlimited)';
       quotaRemaining = 'Unlimited (local zero-cost inference)';
+    } else if (h.id === 'hermes') {
+      identity = 'Hermes Supervisor';
+      plan = 'Autonomous Agent Runtime';
+      rolling5hRemainingPct = '100%';
+      weeklyRemainingPct = '100%';
+      quotaRemaining = 'Active broker & gateway';
+    } else if (h.id === 'dsh') {
+      let model = 'deepseek/deepseek-v4.1-flash';
+      try {
+        const dshModelPath = path.join(os.homedir(), '.dsh', 'default-model.txt');
+        if (fs.existsSync(dshModelPath)) {
+          model = fs.readFileSync(dshModelPath, 'utf8').trim() || model;
+        }
+      } catch {}
+      identity = model;
+      plan = 'DeepSeek Dedicated Harness';
+      rolling5hRemainingPct = '95%';
+      weeklyRemainingPct = '98%';
+      quotaRemaining = 'DeepSeek reasoning pool active';
+    } else if (h.id === 'openclaw') {
+      let channelsStr = 'telegram, qqbot';
+      try {
+        const oPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+        if (fs.existsSync(oPath)) {
+          const oCfg = JSON.parse(fs.readFileSync(oPath, 'utf8'));
+          identity = oCfg?.agents?.defaults?.model?.primary || 'openai-codex/gpt-5.4';
+          if (oCfg?.channels) {
+            channelsStr = Object.keys(oCfg.channels).join(', ');
+          }
+        }
+      } catch {}
+      plan = 'Multi-Channel Gateway';
+      rolling5hRemainingPct = '100%';
+      weeklyRemainingPct = '100%';
+      quotaRemaining = `Channels: ${channelsStr}`;
     }
 
     let status = isAuthed ? 'ready' : 'needs_auth';

package/src/core/plugin-dependencies.mjs

@@ -12,7 +12,8 @@ export function preparePluginDependencies(pluginDir) {
     let source;
     if (name === host.name) source = PACKAGE_ROOT;
     else {
-      source = path.dirname(require.resolve(name));
+      const alias = Object.entries(host.dependencies || {}).find(([, spec]) => typeof spec === 'string' && spec.startsWith(`npm:${name}@`))?.[0];
+      source = path.dirname(require.resolve(alias || name));
       while (true) {
         const file = path.join(source, 'package.json');
         if (fs.existsSync(file) && JSON.parse(fs.readFileSync(file, 'utf8')).name === name) break;

package/src/core/plugin-loader.mjs

@@ -29,7 +29,7 @@ export function globalPluginsDir() {
 }
 
 export function bundledPluginsDir() {
-  return process.env._TR_TEST_BUNDLED_PLUGINS_DIR || path.join(PACKAGE_ROOT, 'plugins');
+  return process.env._TR_TEST_BUNDLED_PLUGINS_DIR || path.join(PACKAGE_ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins');
 }
 
 /** The vault that owns records for plugins installed in `pluginsDir` (`<brain>/plugins` → `<brain>/memory-vault`). */
@@ -165,6 +165,7 @@ export function validatePluginManifest(manifest) {
         if (t.placement !== undefined && !['per-node', 'selected-node'].includes(t.placement)) {
           errors.push(`Task '${t.intent}' has unsupported placement '${t.placement}'`);
         }
+        if (t.timeout_ms !== undefined && (!Number.isInteger(t.timeout_ms) || t.timeout_ms < 1 || t.timeout_ms > 600000)) errors.push(`Task '${t.intent}' timeout_ms must be 1..600000`);
       }
     }
   }

package/src/core/plugin-runner.mjs

@@ -67,6 +67,7 @@ export function runPluginCommand(plugin, options = {}) {
   return new Promise((resolve) => {
     const started = Date.now();
     const chunks = [];
+    const stdoutChunks=[],stderrChunks=[];
     let bytes = 0;
     let truncated = false;
     let timedOut = false;
@@ -90,21 +91,22 @@ export function runPluginCommand(plugin, options = {}) {
       stdio: [stdinText !== undefined ? 'pipe' : stdin === 'inherit' ? 'inherit' : 'ignore', 'pipe', 'pipe']
     });
 
-    const collect = (buf) => {
+    const collect = (buf,stream) => {
       // Even a faulty owner that echoes stdin cannot return credential material.
       if (stdinText !== undefined) return;
       if (truncated) return;
       if (bytes + buf.length > MAX_OUTPUT_BYTES) {
-        chunks.push(buf.subarray(0, MAX_OUTPUT_BYTES - bytes));
+        const partial=buf.subarray(0, MAX_OUTPUT_BYTES - bytes);chunks.push(partial);stream.push(partial);
         bytes = MAX_OUTPUT_BYTES;
         truncated = true;
         return;
       }
       chunks.push(buf);
+      stream.push(buf);
       bytes += buf.length;
     };
-    child.stdout.on('data', collect);
-    child.stderr.on('data', collect);
+    child.stdout.on('data', buf=>collect(buf,stdoutChunks));
+    child.stderr.on('data', buf=>collect(buf,stderrChunks));
     if (stdinText !== undefined) {
       // A handler may exit without reading; EPIPE must not crash the server.
       child.stdin.on('error', () => {});
@@ -124,6 +126,10 @@ export function runPluginCommand(plugin, options = {}) {
       if (spawnError) output += `${output ? '\n' : ''}[runner] ${spawnError.message}`;
       if (truncated) output += `\n[runner] output truncated at ${MAX_OUTPUT_BYTES} bytes`;
       if (timedOut) output += `\n[runner] killed after ${timeoutMs} ms`;
+      let stderr=Buffer.concat(stderrChunks).toString('utf8');
+      if(spawnError)stderr+=`\n[runner] ${spawnError.message}`;
+      if(truncated)stderr+=`\n[runner] output truncated at ${MAX_OUTPUT_BYTES} bytes`;
+      if(timedOut)stderr+=`\n[runner] killed after ${timeoutMs} ms`;
       resolve({
         ok: !spawnError && !timedOut && exitCode === 0,
         exitCode,
@@ -131,6 +137,8 @@ export function runPluginCommand(plugin, options = {}) {
         timedOut,
         truncated,
         output,
+        stdout:Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr,
         durationMs: Date.now() - started
       });
     };

package/src/core/plugin-setup.mjs

@@ -0,0 +1,20 @@
+/** Run declared, enabled plugin setup through the normal isolated CLI runner. */
+import { discoverPlugins } from './plugin-loader.mjs';
+import { readPluginRecord } from './plugin-store.mjs';
+import { runPluginCommand } from './plugin-runner.mjs';
+
+export async function setupInstalledPlugins({root=process.cwd(),plugins=discoverPlugins(root),run=runPluginCommand,record=readPluginRecord}={}) {
+  const results=[];
+  for(const plugin of plugins) {
+    const command=plugin.manifest?.runtime?.setup_command;
+    if(!plugin.valid || !command || record(plugin)?.runtime_enabled===false)continue;
+    if(!plugin.manifest.cli?.subcommands?.some(operation=>operation.name===command)) {
+      results.push({id:plugin.id,ok:false,error:'Runtime setup must name a declared CLI operation'});continue;
+    }
+    try {
+      const result=await run(plugin,{subcommand:command,cwd:root,timeoutMs:600000});
+      results.push({id:plugin.id,ok:result.ok,error:result.ok?undefined:(result.stderr || result.output || 'Plugin setup failed').slice(-1000)});
+    }catch(error){results.push({id:plugin.id,ok:false,error:error.message});}
+  }
+  return {ok:results.every(result=>result.ok),results};
+}

package/src/core/plugin-store.mjs

@@ -364,6 +364,16 @@ export async function installPlugin(source, options = {}) {
   let sourceRecord;
   let verifiedSha = null;
   let dependencies = null;
+  let previousDirectory=null;
+  const prepareDestination=id=>{
+    const target=path.join(pluginsDir,id);
+    if(!options.replace || !fs.existsSync(target))return assertNotInstalled(id,pluginsDir);
+    const archive=path.join(path.dirname(pluginsDir),'memory-derived/plugin-replacements',`${id}-${crypto.randomUUID()}`);
+    fs.mkdirSync(path.dirname(archive),{recursive:true});
+    fs.renameSync(target,archive);previousDirectory={target,archive};
+  };
+
+  try {
 
   const resolved = resolveBundle ? await resolveBundle(source, options) : null;
   const bundled = !resolved && ID_PATTERN.test(source) ? listBundledPlugins().find((p) => p.id === source) : null;
@@ -372,14 +382,14 @@ export async function installPlugin(source, options = {}) {
     manifest = resolved.manifest;
     const validation = validatePluginManifest(manifest);
     if (!validation.valid) throw new Error(`Invalid plugin manifest: ${validation.errors.join('; ')}`);
-    assertNotInstalled(manifest.id, pluginsDir);
+    prepareDestination(manifest.id);
     dest = writeEntriesAtomic(pluginsDir, manifest.id, resolved.entries);
     verifiedSha = resolved.sha256;
     sourceRecord = resolved.source;
   } else if (bundled) {
     if (!bundled.valid) throw new Error(`Bundled plugin '${source}' is invalid: ${bundled.errors.join('; ')}`);
     manifest = bundled.manifest;
-    assertNotInstalled(manifest.id, pluginsDir);
+    prepareDestination(manifest.id);
     dest = copyPluginAtomic(bundled.dir, pluginsDir, manifest.id);
     sourceRecord = { kind: 'bundled', ref: manifest.id };
   } else if (isGitSource(source)) {
@@ -391,7 +401,7 @@ export async function installPlugin(source, options = {}) {
         throw new Error(`Failed to clone ${source}: ${(err.stderr || err.message || '').toString().trim()}`);
       }
       manifest = readManifestFrom(tmp);
-      assertNotInstalled(manifest.id, pluginsDir);
+      prepareDestination(manifest.id);
       dest = copyPluginAtomic(tmp, pluginsDir, manifest.id);
     } finally {
       fs.rmSync(tmp, { recursive: true, force: true });
@@ -403,7 +413,7 @@ export async function installPlugin(source, options = {}) {
       throw new Error(`No bundled plugin, share link, peer source, git URL or directory matches '${source}'`);
     }
     manifest = readManifestFrom(abs);
-    assertNotInstalled(manifest.id, pluginsDir);
+    prepareDestination(manifest.id);
     if (link) {
       fs.mkdirSync(pluginsDir, { recursive: true });
       dest = path.join(pluginsDir, manifest.id);
@@ -446,8 +456,16 @@ export async function installPlugin(source, options = {}) {
     source: sourceRecord,
     sha256,
     dependencies,
+    previousDirectory:previousDirectory?.archive || null,
     compilation
   };
+  }catch(error){
+    if(previousDirectory){
+      if(fs.existsSync(previousDirectory.target))fs.rmSync(previousDirectory.target,{recursive:true,force:true});
+      fs.renameSync(previousDirectory.archive,previousDirectory.target);
+    }
+    throw error;
+  }
 }
 
 export function findInstalled(id, { projectRoot = process.cwd(), global: isGlobal } = {}) {

package/src/core/plugin-tasks.mjs

@@ -99,7 +99,7 @@ export async function runDuePluginTasks(options = {}) {
       const slot = latestDueSlot(cron, runs[task.command], now);
       if (!slot) continue;
 
-      const result = await runner(plugin, { subcommand: task.command, cwd: projectRoot, timeoutMs: TASK_TIMEOUT_MS })
+      const result = await runner(plugin, { subcommand: task.command, cwd: projectRoot, timeoutMs: task.timeout_ms || TASK_TIMEOUT_MS })
         .catch((err) => ({ ok: false, exitCode: null, output: err.message, durationMs: 0, timedOut: false }));
       runs[task.command] = slot;
       changed = true;

package/src/core/project-brain.mjs

@@ -19,6 +19,7 @@ import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import YAML from 'yaml';
+import { ensureRequiredPlugins } from './required-plugins.mjs';
 import { VAULT_CATEGORIES, writeBrainIdentity, registerProjectBrain } from './memory-brain.mjs';
 export { VAULT_CATEGORIES, writeBrainIdentity, registerProjectBrain } from './memory-brain.mjs';
 
@@ -96,6 +97,7 @@ export function ensureOpenWiki(brainDir) {
  * Ensure core total-recall skill package files exist (SKILL.md minimum).
  */
 export function ensureCoreSkillPackage(brainDir) {
+  ensureRequiredPlugins(brainDir);
   const skillMd = path.join(brainDir, 'SKILL.md');
   if (fs.existsSync(skillMd)) return { seeded: false };
   const scaffold = path.join(ROOT, 'scaffold', '.agent', 'skills', 'total-recall');

package/src/core/project-status.mjs

@@ -0,0 +1,64 @@
+/** Read-only inventory of recorded project work. No inferred completion or live readiness. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {listUpdateRoots,resolveRegistryFiles,readRegistryEntries} from './package-auto-update.mjs';
+import {listTasks,resolveQueueDir} from './task-envelope.mjs';
+import {globalBrainDirFor} from './brain-registry.mjs';
+
+export function outstandingProjectStatus(options={}) {
+  const globalBrainDir=options.brainDir || globalBrainDirFor();
+  const roots=listUpdateRoots({...options,brainDir:globalBrainDir});
+  const missing=resolveRegistryFiles({...options,brainDir:globalBrainDir}).flatMap(file=>readRegistryEntries(file)).filter(row=>row.path && !fs.existsSync(row.path)).map(row=>({root:row.path,status:'missing-registered-root'}));
+  const projects=[];
+  const queues=new Set([globalBrainDir]);
+  for(const {root,name} of roots){
+    queues.add(path.join(root,'.agent/skills/total-recall'));
+    const row={name,root,projects:[],status:'no-outstanding-tracker-found'};
+    for(const state of ['in-progress','planned','backlog','blocked']){
+      const directory=path.join(root,'docs/projects',state);
+      if(!fs.existsSync(directory))continue;
+      for(const entry of fs.readdirSync(directory,{withFileTypes:true}).filter(entry=>entry.isDirectory())){
+        const folder=path.join(directory,entry.name);
+        const files=fs.readdirSync(folder).filter(file=>/PROJECT_TRACKER\.md$|^TRACKER\.md$/i.test(file));
+        if(!files.length){row.projects.push({id:entry.name,state,status:'tracker-missing',folder});continue;}
+        for(const file of files){
+          const tracker=path.join(folder,file),body=fs.readFileSync(tracker,'utf8'),lines=body.split(/\r?\n/);
+          const open=lines.flatMap((text,index)=>/^\s*[-*]\s+\[ \]/.test(text)?[{line:index+1,text:text.trim()}]:[]);
+          const done=lines.filter(text=>/^\s*[-*]\s+\[[xX]\]/.test(text)).length;
+          const status=body.match(/^(?:>\s*)?(?:\*\*)?(?:Project Status|Status)\s*:(?:\*\*)?\s*(.+)$/im)?.[1]?.trim() || 'not-declared';
+          const blockers=lines.flatMap((text,index)=>/\b(blocked|blocker|blocking)\b/i.test(text) && !/^\s*[-*]\s+\[[xX]\]/.test(text)?[{line:index+1,text:text.trim()}]:[]);
+          row.projects.push({id:entry.name,state,status,tracker,modifiedAt:fs.statSync(tracker).mtime.toISOString(),openCount:open.length,checkedCount:done,open,blockerMentions:blockers});
+        }
+      }
+    }
+    if(row.projects.length)row.status='recorded-outstanding-work';
+    projects.push(row);
+  }
+  const tasks=[];
+  for(const brainDir of queues)for(const task of listTasks(resolveQueueDir(brainDir),{status:'all'})){
+    if(['completed','cancelled'].includes(task.status))continue;
+    tasks.push({brainDir,slug:task.slug,intent:String(task.intent || '').trim().split(/\r?\n/).find(line=>line.trim() && !line.startsWith('#'))?.slice(0,300) || task.slug,status:task.status,executor:task.executor,priority:task.priority,source:task._filepath});
+  }
+  return {generatedAt:new Date().toISOString(),evidence:'Recorded trackers and task envelopes; live completion and deployments are not verified',rootCount:projects.length,projectCount:projects.reduce((n,row)=>n+row.projects.length,0),openCheckboxCount:projects.reduce((n,row)=>n+row.projects.reduce((m,p)=>m+(p.openCount || 0),0),0),projects,tasks,missing};
+}
+
+export function formatOutstandingProjectStatus(report){
+  const clean=value=>String(value ?? 'unknown').replaceAll('|','\\|').replace(/\s+/g,' ').trim();
+  const lines=['# Outstanding projects and tasks',`Generated ${report.generatedAt}.`,report.evidence,`${report.rootCount} registered roots; ${report.projectCount} project folders; ${report.openCheckboxCount} unchecked items; ${report.tasks.length} outstanding task records.`,'','Counts include duplicated plans in separate repositories. Missing trackers and empty checklists do not establish completion.',''];
+  for(const repo of report.projects){
+    lines.push(`## ${repo.name}`,'',`Source: ${repo.root}`,'');
+    if(!repo.projects.length){lines.push('No outstanding project folder was found in the inspected Kanban directories. Project status remains unverified.','');continue;}
+    lines.push('| Project | Recorded state | Open items | Source updated |','| --- | --- | ---: | --- |');
+    for(const project of repo.projects)lines.push(`| [${clean(project.id)}](${project.tracker || project.folder}) | ${clean(project.state)}${project.status==='tracker-missing'?'; tracker missing':''} | ${project.openCount ?? '?'} | ${project.modifiedAt?.slice(0,10) || 'unknown'} |`);
+    lines.push('');
+    for(const project of repo.projects.filter(project=>project.open?.length)){
+      lines.push(`### ${clean(project.id)}: recorded remaining work`,'');
+      for(const item of project.open)lines.push(`- ${clean(item.text.replace(/^[-*]\s+\[ \]\s*/,''))} ([source](${project.tracker}:${item.line}))`);
+      lines.push('');
+    }
+  }
+  lines.push('## Outstanding daemon tasks','','| Task | Status | Executor | Source |','| --- | --- | --- | --- |');
+  for(const task of report.tasks)lines.push(`| ${clean(task.slug)} | ${clean(task.status)} | ${clean(task.executor)} | [record](${task.source}) |`);
+  for(const row of report.missing)lines.push(`Missing registered root: ${row.root}`);
+  return lines.join('\n')+'\n';
+}