total-recall-brain 3.41.2 → 3.41.4

package/src/core/brain-updates.mjs

@@ -22,6 +22,47 @@ const isLink = file => { try { return fs.lstatSync(file).isSymbolicLink(); } cat
 export const brainUpdateLockPath = owner => path.join(os.tmpdir(),
   `total-recall-update-${createHash('sha256').update(owner).digest('hex')}.lock`);
 
+const pause = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const alive = pid => { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
+
+/**
+ * Take a per-owner update lock. The daemon's hourly `update --automatic` and a
+ * manual `update --all-brains` take the same locks, and a plain exclusive create
+ * failed the manual run outright with EEXIST. A lock whose process is gone is
+ * reclaimed; a live holder is waited for, up to `waitMs`.
+ */
+export function acquireBrainUpdateLock(lock, { waitMs = 600000, pollMs = 1000, isAlive = alive, sleep = pause } = {}) {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      const fd = fs.openSync(lock, 'wx', 0o600);
+      fs.writeFileSync(fd, String(process.pid));
+      return fd;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+    let holder, age;
+    try {
+      holder = Number.parseInt(fs.readFileSync(lock, 'utf8').trim(), 10);
+      age = Date.now() - fs.statSync(lock).mtimeMs;
+    } catch (error) {
+      if (error.code === 'ENOENT') continue; // released between the create and the read
+      throw error;
+    }
+    // A creator writes its pid right after the exclusive create; an empty lock
+    // younger than a few seconds is still being taken, not abandoned. Content
+    // that is not a pid names an unknown owner and is respected.
+    const content = holder ? 'pid' : fs.statSync(lock).size ? 'unknown' : 'empty';
+    const stale = content === 'pid' ? !isAlive(holder) : content === 'empty' && age > 5000;
+    if (stale) {
+      try { fs.unlinkSync(lock); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      continue;
+    }
+    if (Date.now() >= deadline) throw new Error(`Another update (${holder ? `pid ${holder}` : 'unknown owner'}) still holds ${lock}`);
+    sleep(pollMs);
+  }
+}
+
 export function installedBrainPackage(root, key) {
   try {
     const paths = createRequire(path.join(root, 'package.json')).resolve.paths(key) || [];
@@ -44,7 +85,14 @@ export function discoverBrainConsumers(roots, { onError } = {}) {
       let pkg;
       try { pkg = read(file); }
       catch (error) { if (onError) { onError(real, error); return; } throw error; }
-      const deps = sections.flatMap(section => Object.entries(pkg[section] || {})
+      // A plugin copied into a shared plugin folder is installed without its dev
+      // dependencies, on purpose: full dev trees there filled a disk. Counting its
+      // devDependencies made every such plugin a permanently failing consumer, and
+      // "fixing" it would mean installing exactly what must never be installed.
+      const sharedPluginCopy = fs.existsSync(path.join(real, 'plugin.json'))
+        && real.split(path.sep).join('/').includes('/skills/total-recall/plugins/');
+      const deps = sections.filter(section => !(sharedPluginCopy && section === 'devDependencies'))
+        .flatMap(section => Object.entries(pkg[section] || {})
         .filter(([key]) => BRAIN_PACKAGES.includes(canonical(key)) && canonical(key) !== pkg.name)
         .map(([key, declared]) => ({ section, key, package: canonical(key), declared,
           ...installedBrainPackage(real, key) })));
@@ -168,8 +216,7 @@ export async function updateAllBrains(opts = {}) {
       isLink(path.join(consumer.root, 'node_modules')) || consumer.deps.some(dep =>
         dep.version !== versions[dep.package] || !dep.file?.startsWith(path.join(group.owner, 'node_modules') + path.sep)));
     try {
-      lockFd = fs.openSync(lock, 'wx', 0o600);
-      fs.writeFileSync(lockFd, String(process.pid));
+      lockFd = acquireBrainUpdateLock(lock, opts.lockWaitMs === undefined ? {} : { waitMs: opts.lockWaitMs });
       for (const name of ['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml']) {
         const file = path.join(group.owner, name);
         saved.set(file, fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null);
@@ -198,11 +245,22 @@ export async function updateAllBrains(opts = {}) {
       if (install.status !== 0) throw new Error(install.error?.message || install.stderr?.trim().slice(-1500) || `Install exited ${install.status}`);
       for (const { consumer, row } of group.consumers) {
         row.packages = row.packages.map(dep => ({ ...dep, installed: installedBrainPackage(consumer.root, dep.key).version }));
+        // A consumer may legitimately resolve the package from its own node_modules — nested plugin
+        // directories do exactly that. Requiring the owner's hoisted copy reported a correct install
+        // as a failure and rolled the whole batch back, which is why 30 consumers never updated.
+        const allowedRoots = [
+          path.join(group.owner, 'node_modules') + path.sep,
+          path.join(consumer.root, 'node_modules') + path.sep,
+        ];
+        const placed = (file) => Boolean(file) && allowedRoots.some((root) => file.startsWith(root));
         const bad = consumer.deps.find(dep => {
           const actual = installedBrainPackage(consumer.root, dep.key);
-          return actual.version !== versions[dep.package] || !actual.file?.startsWith(path.join(group.owner, 'node_modules') + path.sep);
+          return actual.version !== versions[dep.package] || !placed(actual.file);
         });
-        if (bad || isLink(path.join(consumer.root, 'node_modules'))) throw new Error(`Installed release verification failed: ${consumer.root}${bad ? ` (${bad.key})` : ' (shared link)'}`);
+        // A link is only a fault when it escapes every legitimate root; a self-contained one is fine.
+        const linkPath = path.join(consumer.root, 'node_modules');
+        const linked = isLink(linkPath) && !placed(path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath)));
+        if (bad || linked) throw new Error(`Installed release verification failed: ${consumer.root}${bad ? ` (${bad.key})` : ' (shared link)'}`);
         row.status = 'updated';
       }
     } catch (error) {

package/src/core/cli-commands.mjs

@@ -22,6 +22,8 @@ export const CLI_COMMANDS = {
   edit:     'edit.mjs',
   recall:   'recall.mjs',
   context:  'context.mjs',
+  preflight: 'preflight.mjs',
+  'tr-preflight': 'preflight.mjs',
   'context-stats': 'context-stats.mjs',
   rules:    'rules.mjs',
   search:   'recall.mjs',

package/src/core/context-compiler.mjs

@@ -139,8 +139,15 @@ export async function compileContext({
   return result;
 }
 
+/**
+ * Second line of every text capsule, so output that is truncated or piped through
+ * `head` still carries the rule (the rule once sat at line 544 of the output and
+ * an agent that cut the output at 80 lines never saw it).
+ */
+export const PREFLIGHT_NOTICE = 'PREFLIGHT: before any other tool call, read this whole capsule (never pipe or truncate it), then run: total-recall tr-preflight --ack --task "<task>" --action read,edit,test';
+
 export function renderCapsule(result, format = 'json') {
-  return format === 'text' ? `ready:${result.ready} tokens:${result.stats.total_tokens} version:${result.stats.version}\n${result.context}` : JSON.stringify(result);
+  return format === 'text' ? `ready:${result.ready} tokens:${result.stats.total_tokens} version:${result.stats.version}\n${PREFLIGHT_NOTICE}\n${result.context}` : JSON.stringify(result);
 }
 
 /** Budget the actual wire representation, including metadata, escaping and status. */

package/src/core/default-plugins.mjs

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

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

@@ -6,6 +6,24 @@ import {BRAIN_PACKAGES} from './brain-updates.mjs';
 import {comparePackageVersions} from './package-version.mjs';
 import {updateSourceBrainPackage} from './source-brain-updates.mjs';
 
+/**
+ * A global link that points at a source checkout of `name` under another
+ * directory name (the package was once published as `total-recall`). Missing it
+ * made the update `npm install -g` over the bin and replace the operator's
+ * source checkout with a registry copy.
+ */
+export function findLinkedSourceCheckout(root,name){
+  let entries=[];try{entries=fs.readdirSync(root,{withFileTypes:true});}catch{return null;}
+  for(const entry of entries){
+    if(!entry.isSymbolicLink())continue;
+    try{
+      const dir=fs.realpathSync(path.join(root,entry.name));
+      if(JSON.parse(fs.readFileSync(path.join(dir,'package.json'),'utf8')).name===name&&fs.existsSync(path.join(dir,'.git')))return dir;
+    }catch{}
+  }
+  return null;
+}
+
 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'}]};
@@ -13,7 +31,9 @@ export function updateGlobalBrainPackages({versions,exec=spawnSync,sourceUpdate=
   const results=[];
   const install=[];
   for(const name of BRAIN_PACKAGES){
-    const directory=path.join(root,name),file=path.join(directory,'package.json');
+    let directory=path.join(root,name);
+    if(!fs.existsSync(directory))directory=findLinkedSourceCheckout(root,name)||directory;
+    const 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;

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

@@ -15,14 +15,17 @@ export async function updateMeshBrainPackages({version,versions,listNodes,exec,n
       // 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']);
+      const localFailed=report?(report.local_failed ?? Math.max(0,(report.failed || 0)-(report.mesh?.failed || 0))):null;
+      const current=observed.success && report && localFailed===0 && 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';
+      row.error=!launched.success?launched.stderr || 'Mesh maintenance dispatch failed'
+        :localFailed?`Peer reports ${localFailed} local maintenance failure(s); re-dispatched`
+        :'Awaiting independently verified remote report';
     }catch(error){row.status='failed';row.error=error.message;}
   }
   // A dispatched process is not a verified update. Keep it visible for retries.

package/src/core/meta-harness.mjs

@@ -49,15 +49,6 @@ export const HARNESS_SPECS = {
     execType: 'subcommand',
     description: 'Autonomous program synthesis and sandbox execution.'
   },
-  gemini: {
-    id: 'gemini',
-    name: 'Google Gemini CLI',
-    binary: 'gemini',
-    category: 'fast_utility',
-    defaultFlags: ['--sandbox=false', '--yolo', '-o', 'json'],
-    execType: 'flag_last',
-    description: 'High-speed utility completions and tool chaining.'
-  },
   ollama: {
     id: 'ollama',
     name: 'Ollama Local LLM',
@@ -246,14 +237,6 @@ export async function detectHarnessesWithAuth({ readSecret = readStoreSecret } =
         h.authed = true;
         h.authRoute = 'cached-xai-auth';
       }
-    } else if (h.id === 'gemini') {
-      if (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY) {
-        h.authed = true;
-        h.authRoute = 'env-api-key';
-      } else if (fs.existsSync(path.join(os.homedir(), '.gemini'))) {
-        h.authed = true;
-        h.authRoute = 'cached-google-signin';
-      }
     } else if (h.id === 'hermes') {
       if (process.env.HERMES_API_KEY) {
         h.authed = true;
@@ -471,6 +454,9 @@ export function getInstalledHarnessVersion(harnessId) {
       const m = (res.stdout || '').match(/(\d+\.\d+\.\d+)/);
       if (m) return m[1];
     } else if (harnessId === 'codex') {
+      const res = spawnSync('codex', ['--version'], { timeout: 1500, encoding: 'utf8' });
+      const m = (res.stdout || '').match(/(\d+\.\d+\.\d+)/);
+      if (m) return m[1];
       const candidatePaths = [
         path.join(os.homedir(), '.nvm/versions/node/v24.12.0/lib/node_modules/@openai/codex/package.json'),
         '/usr/local/lib/node_modules/@openai/codex/package.json',
@@ -496,10 +482,6 @@ export function getInstalledHarnessVersion(harnessId) {
       const res = spawnSync('ollama', ['--version'], { timeout: 1500, encoding: 'utf8' });
       const m = (res.stdout || res.stderr || '').match(/(\d+\.\d+\.\d+)/);
       if (m) return m[1];
-    } else if (harnessId === 'gemini') {
-      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+)/);
@@ -550,19 +532,24 @@ export async function getLatestHarnessVersion(harnessId, installedVersion = 'unk
         if (d.version) latest = d.version;
       }
     } else if (harnessId === 'agy') {
-      latest = '1.3.1';
+      try {
+        const res = spawnSync('agy', ['changelog'], { timeout: 2000, encoding: 'utf8' });
+        const m = (res.stdout || '').match(/^(\d+\.\d+\.\d+):/m);
+        if (m) latest = m[1];
+        else latest = installedVersion !== 'unknown' ? installedVersion : '1.4.12';
+      } catch {
+        latest = installedVersion !== 'unknown' ? installedVersion : '1.4.12';
+      }
     } else if (harnessId === 'grok') {
-      latest = '0.2.118';
+      latest = installedVersion !== 'unknown' ? installedVersion : '0.2.118';
     } else if (harnessId === 'ollama') {
-      latest = '0.24.0';
-    } else if (harnessId === 'gemini') {
-      latest = '0.3.0';
+      latest = installedVersion !== 'unknown' ? installedVersion : 'unknown';
     } else if (harnessId === 'hermes') {
-      latest = '0.1.0';
+      latest = installedVersion !== 'unknown' ? installedVersion : 'unknown';
     } else if (harnessId === 'dsh') {
-      latest = '1.1.1';
+      latest = installedVersion !== 'unknown' ? installedVersion : 'unknown';
     } else if (harnessId === 'openclaw') {
-      latest = '2026.4.10';
+      latest = installedVersion !== 'unknown' ? installedVersion : 'unknown';
     }
   } catch {}
 
@@ -593,9 +580,9 @@ export async function queryHarnessUsage() {
         status: 'not_installed',
         identity: '—',
         plan: '—',
-        rolling5hRemainingPct: '0%',
-        weeklyRemainingPct: '0%',
-        quotaRemaining: 'Not available'
+        rolling5hRemainingPct: '—',
+        weeklyRemainingPct: '—',
+        quotaRemaining: 'not installed'
       });
       continue;
     }
@@ -606,9 +593,13 @@ export async function queryHarnessUsage() {
 
     let identity = 'Detected local install';
     let plan = 'Standard';
-    let quotaRemaining = 'Active';
-    let rolling5hRemainingPct = '100%';
-    let weeklyRemainingPct = '100%';
+    // Never invent a quota. These fields held hardcoded literals ('100%', '98%', '85%') that read
+    // like measurements but came from no source at all — no provider usage endpoint was called, so
+    // the table reported fictional headroom for every harness. A figure appears here only when a
+    // real source produced it; otherwise the value is honestly unknown.
+    let quotaRemaining = 'unknown — no usage endpoint integrated';
+    let rolling5hRemainingPct = '—';
+    let weeklyRemainingPct = '—';
     let isAuthed = h.authed;
     let authRoute = h.authRoute;
 
@@ -620,9 +611,6 @@ export async function queryHarnessUsage() {
           if (acc.active) identity = acc.active;
         }
         plan = 'Google AI Ultra / Pro';
-        rolling5hRemainingPct = '100%';
-        weeklyRemainingPct = '98%';
-        quotaRemaining = '5h window: 100% | Weekly compute: 98%';
       } catch {}
     } else if (h.id === 'claude') {
       try {
@@ -632,9 +620,6 @@ export async function queryHarnessUsage() {
           if (cData.userID) identity = `User: ${cData.userID.slice(0, 8)}...`;
           plan = cData.opusProMigrationComplete ? 'Claude Pro / Max (Opus enabled)' : 'Claude Pro';
         }
-        rolling5hRemainingPct = '85%';
-        weeklyRemainingPct = '92%';
-        quotaRemaining = '5h window: 85% remaining | Weekly cap: 92% remaining';
       } catch {}
     } else if (h.id === 'codex') {
       try {
@@ -659,15 +644,7 @@ export async function queryHarnessUsage() {
           }
           plan = 'ChatGPT Subscription (GPT-4o/Codex)';
         }
-        if (isAuthed) {
-          rolling5hRemainingPct = '94%';
-          weeklyRemainingPct = '96%';
-          quotaRemaining = '5h reasoning: 94% remaining | Weekly quota: 96% remaining';
-        } else {
-          rolling5hRemainingPct = '0% (expired)';
-          weeklyRemainingPct = '0% (expired)';
-          quotaRemaining = 'Authentication expired';
-        }
+        if (!isAuthed) quotaRemaining = 'unavailable — authentication expired';
       } catch {}
     } else if (h.id === 'grok') {
       try {
@@ -685,27 +662,7 @@ export async function queryHarnessUsage() {
           }
           plan = 'Grok Build Tier';
         }
-        if (isAuthed) {
-          rolling5hRemainingPct = '100%';
-          weeklyRemainingPct = '100%';
-          quotaRemaining = '5h rate window: 100% | Weekly allowance: 100%';
-        } else {
-          rolling5hRemainingPct = '0% (expired)';
-          weeklyRemainingPct = '0% (expired)';
-          quotaRemaining = 'Token expired (refresh needed)';
-        }
-      } catch {}
-    } else if (h.id === 'gemini') {
-      try {
-        const accPath = path.join(os.homedir(), '.gemini', 'google_accounts.json');
-        if (fs.existsSync(accPath)) {
-          const acc = JSON.parse(fs.readFileSync(accPath, 'utf8'));
-          if (acc.active) identity = acc.active;
-        }
-        plan = 'Google AI API / Subscription';
-        rolling5hRemainingPct = '100%';
-        weeklyRemainingPct = '100%';
-        quotaRemaining = 'Standard rate limits active';
+        if (!isAuthed) quotaRemaining = 'unavailable — token expired (refresh needed)';
       } catch {}
     } else if (h.id === 'ollama') {
       identity = 'Local Machine';
@@ -716,9 +673,7 @@ export async function queryHarnessUsage() {
     } else if (h.id === 'hermes') {
       identity = 'Hermes Supervisor';
       plan = 'Autonomous Agent Runtime';
-      rolling5hRemainingPct = '100%';
-      weeklyRemainingPct = '100%';
-      quotaRemaining = 'Active broker & gateway';
+      quotaRemaining = 'local runtime — no metered quota';
     } else if (h.id === 'dsh') {
       let model = 'deepseek/deepseek-v4.1-flash';
       try {
@@ -729,9 +684,9 @@ export async function queryHarnessUsage() {
       } catch {}
       identity = model;
       plan = 'DeepSeek Dedicated Harness';
-      rolling5hRemainingPct = '95%';
-      weeklyRemainingPct = '98%';
-      quotaRemaining = 'DeepSeek reasoning pool active';
+      // dsh bills through OpenRouter metered credit and publishes no quota figures of its own, so
+      // none are shown. Point the reader at the one place the real number exists.
+      quotaRemaining = 'metered — see OpenRouter credits';
     } else if (h.id === 'openclaw') {
       let channelsStr = 'telegram, qqbot';
       try {
@@ -745,8 +700,6 @@ export async function queryHarnessUsage() {
         }
       } catch {}
       plan = 'Multi-Channel Gateway';
-      rolling5hRemainingPct = '100%';
-      weeklyRemainingPct = '100%';
       quotaRemaining = `Channels: ${channelsStr}`;
     }
 

package/src/core/plugin-dependencies.mjs

@@ -13,7 +13,12 @@ export function preparePluginDependencies(pluginDir) {
     if (name === host.name) source = PACKAGE_ROOT;
     else {
       const alias = Object.entries(host.dependencies || {}).find(([, spec]) => typeof spec === 'string' && spec.startsWith(`npm:${name}@`))?.[0];
-      source = path.dirname(require.resolve(alias || name));
+      const targetPkg = alias || name;
+      try {
+        source = path.dirname(require.resolve(targetPkg));
+      } catch {
+        source = path.dirname(require.resolve(`${targetPkg}/package.json`));
+      }
       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-runner.mjs

@@ -56,7 +56,12 @@ export function runPluginCommand(plugin, options = {}) {
   if (!pluginExecutionEnabled(plugin, { projectRoot: cwd }) && !['status', 'health', 'jobs', '--help', '-h', 'help'].includes(operation)) {
     return Promise.reject(new Error(`Plugin ${plugin.id} is inactive; run total-recall plugin on ${plugin.id}`));
   }
-  const declaredTimeout = plugin?.manifest?.cli?.subcommands?.find(item => item.name === operation)?.timeout_ms;
+  // Manifests declare this as `timeoutMs`; the runner only read `timeout_ms`, so every declared
+  // timeout was ignored and each command fell back to DEFAULT_TIMEOUT_MS (30s). That killed work
+  // that legitimately takes longer — `mesh nodes` and `tr-transcribe transcribe` (model load) both
+  // died at 30s while their manifests asked for far more. Accept both spellings.
+  const declaration = plugin?.manifest?.cli?.subcommands?.find(item => item.name === operation);
+  const declaredTimeout = declaration?.timeout_ms ?? declaration?.timeoutMs;
   const timeoutMs = requestedTimeoutMs ?? declaredTimeout ?? DEFAULT_TIMEOUT_MS;
   if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600000) return Promise.reject(new Error('Plugin timeout must be 1..600000 ms'));
   const handlerRel = plugin?.manifest?.cli?.handler;

package/src/core/plugin-store.mjs

@@ -417,6 +417,67 @@ export async function installPluginDependencies(dest, id) {
   return { installed: true, packages };
 }
 
+const REPLACEMENT_NAME = /^(.+)-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+
+/** Where `install --replace` keeps the copy it replaced, beside a plugins directory. */
+export function replacementArchiveDir(pluginsDir) {
+  return path.join(path.dirname(pluginsDir), 'memory-derived', 'plugin-replacements');
+}
+
+function directoryBytes(dir) {
+  let total = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) total += directoryBytes(full);
+    else if (entry.isFile()) total += fs.statSync(full).size;
+  }
+  return total;
+}
+
+/**
+ * Bound the copies `install --replace` keeps. Every replacement archives the
+ * previous install, dependencies included, and nothing removed them, so the
+ * hourly automatic plugin update grew the archive without limit: 73 copies
+ * filled a laptop disk. Keep the newest `keep` copies of each plugin (or of
+ * `id` only), without node_modules, which a rollback reinstalls. A rename
+ * keeps a directory's old mtime, so the copy just archived is named in
+ * `prefer` and always counts as the newest.
+ *
+ * @param {string} archiveDir
+ * @param {{ id?: string, keep?: number, apply?: boolean, prefer?: string }} [opts]
+ */
+export function pruneReplacementArchives(archiveDir, { id, keep = 1, apply = true, prefer } = {}) {
+  if (!fs.existsSync(archiveDir)) return { archiveDir, kept: [], removed: [], stripped: [], bytesFreed: 0 };
+  const byId = new Map();
+  for (const name of fs.readdirSync(archiveDir)) {
+    const m = REPLACEMENT_NAME.exec(name);
+    const full = path.join(archiveDir, name);
+    if (!m || (id && m[1] !== id) || !fs.statSync(full).isDirectory()) continue;
+    (byId.get(m[1]) || byId.set(m[1], []).get(m[1])).push({ name, full, mtime: fs.statSync(full).mtimeMs });
+  }
+  const kept = [], removed = [], stripped = [];
+  let bytesFreed = 0;
+  for (const copies of byId.values()) {
+    copies.sort((a, b) => (b.name === prefer) - (a.name === prefer) || b.mtime - a.mtime);
+    copies.forEach((copy, index) => {
+      if (index >= keep) {
+        bytesFreed += directoryBytes(copy.full);
+        if (apply) fs.rmSync(copy.full, { recursive: true, force: true });
+        removed.push(copy.name);
+        return;
+      }
+      kept.push(copy.name);
+      const modules = path.join(copy.full, 'node_modules');
+      if (fs.existsSync(modules)) {
+        bytesFreed += directoryBytes(modules);
+        if (apply) fs.rmSync(modules, { recursive: true, force: true });
+        stripped.push(copy.name);
+      }
+    });
+  }
+  return { archiveDir, kept, removed, stripped, bytesFreed };
+}
+
 /**
  * Install a plugin.
  * @param {string} source  bundled id | public share URL | `peer:<host>/<id>` | git URL | local path
@@ -439,7 +500,7 @@ export async function installPlugin(source, options = {}) {
   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()}`);
+    const archive=path.join(replacementArchiveDir(pluginsDir),`${id}-${crypto.randomUUID()}`);
     fs.mkdirSync(path.dirname(archive),{recursive:true});
     fs.renameSync(target,archive);previousDirectory={target,archive};
   };
@@ -524,6 +585,11 @@ export async function installPlugin(source, options = {}) {
     throw new Error(`Plugin files were written but its record could not be: ${err.message}`);
   }
 
+  // The install succeeded: keep only this replacement's copy of the plugin, without dependencies.
+  if (previousDirectory) {
+    pruneReplacementArchives(replacementArchiveDir(pluginsDir), { id: manifest.id, keep: 1, prefer: path.basename(previousDirectory.archive) });
+  }
+
   // A batch of installs (automatic updates) compiles once after the batch instead.
   const compilation = options.recompile === false ? { skipped: true } : await recompileAfterPluginMutation(projectRoot, isGlobal);
   return {

package/src/core/plugin-updates.mjs

@@ -50,7 +50,7 @@ export async function checkPlugin(plugin, { gitHead = remoteGitHead, peerHash =
       return { status: 'pinned', ref: source.ref };
     case 'bundled': {
       const shipped = bundled().find(p => p.id === id);
-      if (!shipped) return { status: 'failed', error: `Bundled plugin '${id}' is no longer shipped in this package` };
+      if (!shipped) return { status: 'failed', error: `Bundled plugin '${id}' is no longer shipped in this package; reinstall it from its git repository with: total-recall plugin install <git-url> --global --replace` };
       return hashPluginDir(shipped.dir).sha256 === plugin.installed_sha256 ? { status: 'current' } : { status: 'behind', install: id };
     }
     case 'git': {

package/src/core/portable-skills-maintenance.mjs

@@ -0,0 +1,19 @@
+/** Existing daemon maintenance verifies explicitly enrolled owner skill packages. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRegistry } from './skills-registry.mjs';
+import { runBounded } from './startup-health.mjs';
+
+export async function maintainPortableSkills({ brainDir, apply = true, run = runBounded } = {}) {
+  const entry = loadRegistry(brainDir).skills.ssss;
+  if (!entry || !entry.layered || entry.source_type !== 'portable-owner-package') return { skipped: true, reason: 'no-enrolled-portable-source', failed: 0, results: [] };
+  const script = path.join(entry.source_path, 'core/scripts/maintain.mjs');
+  if (!fs.existsSync(script)) return { failed: 1, results: [], error: 'Registered portable source maintenance helper is missing' };
+  const result = await run(process.execPath, [script, '--source', entry.source_path, ...(apply ? ['--apply'] : [])], { timeoutMs: 5 * 60 * 1000, maxBytes: 8 * 1024 * 1024 });
+  try {
+    const report = JSON.parse(result.output);
+    return { ...report, failed: Math.max(report.failed || 0, result.code === 0 ? 0 : 1) };
+  } catch {
+    return { failed: 1, results: [], error: result.reason || result.output || 'Portable skill verification returned no report' };
+  }
+}

package/src/core/preflight-gate.mjs

@@ -0,0 +1,77 @@
+/**
+ * Harness-neutral gate decision. Every harness adapter normalises its native
+ * hook payload into `{ tool, command, path, cwd }` and asks `decide`; the answer
+ * is the same in every harness.
+ *
+ * Rules, in order:
+ *   1. Tools that only display or discover (`meta`, `ui`) are always open.
+ *   2. Reads of skill files are open: reading them is how the preflight is earned.
+ *   3. A single plain Total Recall preflight, context, recall or help command is
+ *      open, so the gate can always be satisfied or repaired. Chaining, piping,
+ *      substitution and redirects are not plain, so the exemption cannot carry
+ *      other work and a capsule cannot be truncated through a pipe.
+ *   4. Everything else needs a fresh receipt for the directory.
+ *   5. With a receipt, a repository-wide source sweep still needs a recent
+ *      Total Recall consult (the rule DSH enforced alone until now).
+ * Any error inside the gate denies: most harnesses fail open when a hook crashes.
+ */
+import { ACK_COMMAND } from './preflight-receipt.mjs';
+
+export const TOOL_CLASSES = ['shell', 'read', 'write', 'search', 'web', 'mcp', 'agent', 'meta', 'ui', 'other'];
+export const SWEEP_CONSULT_MS = 15 * 60 * 1000;
+
+const SKILL_PATH = /\/\.(agent|claude)\/skills\//;
+const SATISFYING = /^(cd\s+\S+\s*&&\s*)?(npx\s+)?(total-recall|node\s+\S*bin\/total-recall\.mjs)\s+(tr-preflight|preflight|context|recall|help|--help)(\s+[^;&|`<>$\n]*)?$/;
+
+/** True when the whole command is one plain Total Recall invocation that satisfies or repairs the gate. */
+export function isSatisfyingCommand(command) {
+  return SATISFYING.test(String(command || '').trim());
+}
+
+/** A repository-wide search used to answer a question, as the DSH `tr-first.sh` rule defined it. */
+export function isRepoSweep(command) {
+  const c = String(command || '');
+  if (c.includes('total-recall')) return false;
+  const sweep = /(^|[\s;&|(])(rg|ripgrep|ag)\s/.test(c)
+    || /(^|[\s;&|(])grep\s+(-[A-Za-z]*[rR][A-Za-z]*|--recursive)(\s|$)/.test(c)
+    || /(^|[\s;&|(])find\s+(\.|\/Users)/.test(c)
+    || /(^|[\s;&|(])git\s+grep(\s|$)/.test(c);
+  if (!sweep) return false;
+  if (/\|\s*(grep|rg|ag)(\s|$)/.test(c)) return false; // filtering command output is not a source question
+  if (/node_modules|\.agent\/skills|\/tmp\/|\.git\//.test(c)) return false;
+  return true;
+}
+
+const allow = (rule) => ({ decision: 'allow', rule });
+const deny = (rule, reason, fix = ACK_COMMAND) => ({ decision: 'deny', rule, reason, fix });
+
+/**
+ * @param {{ tool: string, command?: string, path?: string, cwd?: string }} call
+ * @param {{ check: () => { ok: boolean, problems: string[] }, recentConsult?: () => boolean, readablePaths?: RegExp[] }} deps
+ */
+export function decide(call, deps) {
+  try {
+    const tool = TOOL_CLASSES.includes(call?.tool) ? call.tool : 'other';
+    if (tool === 'meta' || tool === 'ui') return allow(`class:${tool}`);
+    if (tool === 'read') {
+      const target = String(call.path || '');
+      if (SKILL_PATH.test(target)) return allow('read:skill-file');
+      // Persisted output of an allowed command is readable; each adapter names its host's paths (audit F-019).
+      if ((deps.readablePaths || []).some((re) => re.test(target))) return allow('read:persisted-output');
+    }
+    if (tool === 'shell' && isSatisfyingCommand(call.command)) return allow('shell:satisfying-command');
+
+    const receipt = deps.check();
+    if (!receipt.ok) {
+      return deny('receipt', `TR-PREFLIGHT gate: ${receipt.problems[0] || 'check failed'} (directory: ${call.cwd || 'unknown'}). `
+        + 'No work may start until it passes. Read the complete context capsule (never pipe or truncate it), then acknowledge.');
+    }
+    if (tool === 'shell' && isRepoSweep(call.command) && !(deps.recentConsult ? deps.recentConsult() : false)) {
+      return deny('sweep', 'TR-PREFLIGHT gate: do not sweep the repository for an answer; Total Recall owns it. Run `total-recall help "<task>"` to find the owning command, or `total-recall recall "<topic>" --local`, then repeat this call.',
+        'total-recall help "<task>"');
+    }
+    return allow('receipt:fresh');
+  } catch (err) {
+    return deny('gate-error', `TR-PREFLIGHT gate error: ${err.message}. The gate fails closed.`);
+  }
+}