total-recall-brain 3.43.3 → 3.45.0

package/src/cli/plugin/install.mjs

@@ -2,18 +2,22 @@ import { installPlugin as install } from '../../core/plugin-distribution.mjs';
 import { syncPluginCommands } from '../command.mjs';
 
 export async function installPlugin(args = []) {
-  const isGlobal = args.includes('--global') || args.includes('-g');
+  // Every plugin installs into the shared folder; `--global` is accepted and changes nothing.
   const isLink = args.includes('--link') || args.includes('-l');
   const source = args.find(a => !a.startsWith('-'));
 
+  if (args.includes('--project')) {
+    console.error("❌ Plugins are installed only in the shared folder. In a repository, switch one with 'total-recall plugin on|off <id>'.");
+    process.exit(1);
+  }
   if (!source) {
     console.error('❌ Error: Missing plugin source.');
-    console.error('   Usage: total-recall plugin install <bundled-id | share-link | peer:<host>/<id> | git-url | path> [--link] [--global]\n');
+    console.error('   Usage: total-recall plugin install <bundled-id | share-link | peer:<host>/<id> | git-url | path> [--link]\n');
     process.exit(1);
   }
 
   try {
-    const result = await install(source, { projectRoot: process.cwd(), global: isGlobal, link: isLink, replace:args.includes('--replace') });
+    const result = await install(source, { projectRoot: process.cwd(), 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}`);
@@ -24,7 +28,7 @@ export async function installPlugin(args = []) {
     } else if (result.dependencies?.reason && !['no package.json', 'no dependencies declared'].includes(result.dependencies.reason)) {
       console.log(`   Dependencies: NOT installed (${result.dependencies.reason})`);
     }
-    const cmds = syncPluginCommands(result.plugin.dir, { global: isGlobal });
+    const cmds = syncPluginCommands(result.plugin.dir, { global: true });
     if (cmds.created.length) console.log(`   Commands: ${cmds.created.map((c) => `total-recall ${c}`).join(', ')}`);
     for (const c of cmds.skipped) console.log(`   Skipped command '${c.name}': ${c.reason}`);
     console.log('');
@@ -34,17 +38,8 @@ export async function installPlugin(args = []) {
       return;
     }
     const { autoCompileSurfaces } = await import('../../core/auto-compile.mjs');
-    // Compile the layer the plugin actually landed in. `scope` is not enough on
-    // its own: from a directory with no project brain, projectPluginsDir(cwd)
-    // resolves to the global plugins dir, so a plugin installed into the global
-    // brain still reports scope 'project'. Ask the resolver whether a project
-    // brain exists at all, and otherwise fall back to the global layer — the one
-    // that was really written. Assuming 'project' compiled nothing and printed
-    // "Auto-compile failed: No project brain found" after a successful install.
-    const { resolveBrainDir } = await import('../agent-dir.mjs');
-    let targetLayer = 'global';
-    try { resolveBrainDir('project'); targetLayer = 'project'; } catch { targetLayer = 'global'; }
-    if (!await autoCompileSurfaces({ layer: targetLayer, semantic: false, force: true })) process.exitCode = 1;
+    // The plugin landed in the shared folder, so the global layer is the one to compile.
+    if (!await autoCompileSurfaces({ layer: 'global', semantic: false, force: true })) process.exitCode = 1;
   } catch (err) {
     console.error(`❌ ${err.message}`);
     process.exit(1);

package/src/cli/plugin/remove.mjs

@@ -8,7 +8,7 @@ export async function removePlugin(args = []) {
 
   if (!id) {
     console.error('❌ Error: Missing plugin ID to remove.');
-    console.error('   Usage: total-recall plugin remove <id> [--global]\n');
+    console.error('   Usage: total-recall plugin remove <id>\n');
     process.exit(1);
   }
 

package/src/cli/plugin/search.mjs

@@ -22,7 +22,7 @@ function parseArgs(args) {
  * `includes` makes a short query match inside unrelated words: searching "git"
  * returned the signing plugin, whose description begins "Digital agreement…".
  * A hit inside a word is only accepted at a word start so that real substrings
- * still work ("sent" finds "git-sentinel") without matching "digital".
+ * still work ("qual" finds "code-quality") without matching "digital".
  */
 function matches(p, query, useCase) {
   if (useCase && !(p.use_cases || []).includes(useCase)) return false;
@@ -32,7 +32,7 @@ function matches(p, query, useCase) {
   const words = query.split(/\s+/).filter(Boolean);
   return words.every((word) => {
     const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    // Anchor at a word start so "sent" matches "git-sentinel" but "git" does
+    // Anchor at a word start so "qual" matches "code-quality" but "git" does
     // not match "digital".
     const bounded = new RegExp(`(^|[^a-z0-9])${escaped}`, 'i');
     return haystacks.some((h) => bounded.test(h) || h.startsWith(word));

package/src/cli/preflight.mjs

@@ -1,16 +1,18 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { ensureDependencies } from '../core/ensure-dependencies.mjs';
 import { detectProjectBrain } from '../core/brain-locate.mjs';
 import { globalBrainDirFor, isBrainEnabled } from '../core/brain-registry.mjs';
 import { GATE_MODES, gateConfigPath, projectBrainDir, readGateLayers, resolveGateMode, writeGateMode } from '../core/gate-mode.mjs';
 import { installHarnessHooks, loadGateAdapters } from '../core/harness-hooks.mjs';
-import { ackDirectory, capsuleVerb, decide, isAckCommand, isCheckCommand, isRouteCommand, isSubagentPayload, nativeToolOf, sessionOf, SWEEP_CONSULT_MS, whenGateFails } from '../core/preflight-gate.mjs';
+import { ackDirectory, capsuleVerb, decide, gatePackageBroken, isAckCommand, isCheckCommand, isRouteCommand, isSubagentPayload, nativeToolOf, sessionOf, SWEEP_CONSULT_MS, whenGateFails } from '../core/preflight-gate.mjs';
 import { ACK_COMMAND, acknowledge, checkAgentReceipt, checkAnyReceipt, findRoot, forgetCapsuleDeliveries, lastArrivalMs, lastCapsuleDelivery, lastConsultMs, lastRoutedMs, lastRouteWarnedMs, lastSessionAck, markArrival, markDelegated, markRouted, markRouteWarned, markSessionAck, noteCaller, recordDecision, sessionHasStanding, sessionKey, readDecisions, takeCaller } from '../core/preflight-receipt.mjs';
 
 const USAGE = `Usage: total-recall preflight <command>
   ack --task "<task>" [--action read,edit,test] [--json]   Record a receipt after context ready:true and rules verify, and print the capsule.
                                                             Prints one line instead when this session received the same rules and skills within 2 hours
+                                                            Restores missing or stale locked dependencies for edit/test actions
   check [--json]                                            Exit 1 unless a fresh receipt covers this agent, wherever it acknowledged.
                                                             Run by hand, it reports this directory's receipt
   gate [--harness <id>]                                     Hook entry: read a call on stdin, answer allow or deny (exit 2 on deny)
@@ -81,12 +83,23 @@ async function ack(args) {
   const task = flag(args, '--task') || '';
   const actions = flag(args, '--action') || 'read,edit,test';
   const result = acknowledge({ root, task, actions, maxAgeMs: await configuredMaxAgeMs(), session: takeCaller(root, 'ack', { task }) });
+  const needsDependencies = actions.split(',').some(action => ['edit', 'test'].includes(action.trim()));
+  const dependencies = result.ok && needsDependencies ? await ensureDependencies(root, { reason: `preflight:${actions}` }) : null;
+  const ok = result.ok && dependencies?.ok !== false;
   if (args.includes('--json')) {
-    console.log(JSON.stringify({ ok: result.ok, problems: result.problems, receipt: result.file || null, capsule: result.capsule ?? null, unchanged: Boolean(result.unchanged) }));
-    if (!result.ok) process.exitCode = 1;
+    console.log(JSON.stringify({ ok, problems: [...result.problems, ...(dependencies?.ok === false ? [`dependencies: ${dependencies.error}`] : [])], receipt: result.file || null, capsule: result.capsule ?? null, unchanged: Boolean(result.unchanged), dependencies }));
+    if (!ok) process.exitCode = 1;
     return;
   }
   if (!result.ok) return printFailure(result.problems);
+  if (dependencies) {
+    const detail = dependencies.ok ? (dependencies.command?.join(' ') || dependencies.trigger) : dependencies.error;
+    console.log(`  dependencies: ${dependencies.status} — ${detail}`);
+    if (!dependencies.ok) {
+      console.error('✖ Dependency install failed. Repair dependencies before edit or test work. The instruction receipt is recorded.');
+      process.exitCode = 1;
+    }
+  }
   if (result.unchanged) {
     const age = result.unchanged.ageMs < 60000 ? 'less than a minute ago' : `${Math.round(result.unchanged.ageMs / 60000)} minutes ago`;
     console.log(`✔ tr-preflight recorded: rules and skills are unchanged since this session received the capsule ${age}, so there is nothing new to read. If your task is new, or you no longer have the capsule, run: total-recall context "<task>" --action ${actions}`);
@@ -398,6 +411,8 @@ function evaluate(call, options = {}) {
 }
 
 function judge(call, { harness, readablePaths, session = null, subagent = false, nativeTool = null } = {}) {
+  const broken = gatePackageBroken();
+  if (broken) return whenGateFails(call, new Error(broken));
   const root = findRoot(call.cwd || process.cwd());
   const limit = envMaxAgeMs();
   const declared = readGateDeclarations();
@@ -584,12 +599,10 @@ async function mode(args) {
 
 export default async function preflight(args = []) {
   const [first = '--help'] = args;
-  if (first === '--help' || first === '-h' || first === 'help') return console.log(USAGE);
+  if (first === '--help' || first === '-h' || first === 'help' || args.includes('--help') || args.includes('-h')) return console.log(USAGE);
   // Original `tr-preflight` forms.
   if (first === '--ack' || first === 'ack') return ack(args);
   if (first === '--check' || first === 'check') return check(args);
-  // Help never performs the subcommand: `install --help` once rewrote the harness settings (C-019).
-  if (args.includes('--help') || args.includes('-h')) return console.log(USAGE);
   if (first === 'gate') return gate(args.slice(1));
   if (first === 'remind') return remind(args);
   if (first === 'session-start') return sessionStart();

package/src/cli/proposals.mjs

@@ -208,7 +208,7 @@ export default async function proposals(args) {
         console.log(`  ${String(days).padStart(4)}d  [i${n.importance}]  ${n.slug}`);
       }
       if (stale.length > 40) console.log(`\n  … and ${stale.length - 40} more.`);
-      console.log('\n  The dream cycle queues these for research automatically.\n');
+      console.log('\n  This query is read-only. Request research explicitly for a node that needs verification.\n');
       return;
     }
 

package/src/cli/recall.mjs

@@ -1,5 +1,22 @@
 import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
 import path from 'node:path';
+import fs from 'node:fs';
+
+/** One brain search shared by recall and paired evaluation. Does not record access. */
+export async function searchRecallBrain(query, { semantic = false, forceFast = false, field = false, ...options } = {}) {
+  let rankResults = null;
+  if (field) {
+    const { loadField, rankWithField } = await import('../core/vector-field.mjs');
+    const compiled = loadField(options.derivedDir);
+    if (!compiled) throw new Error('Vector field missing or corrupt. Run total-recall recall --compile-field first.');
+    rankResults = results => rankWithField(results, { field: compiled, derivedDir: options.derivedDir });
+  }
+  const { fastSearch } = await import('../core/fast-recall.mjs');
+  const fastResults = fastSearch(query, { ...options, fullText: !forceFast, rankResults });
+  if (!semantic || fastResults.some(result => (result.base_score ?? result.score) === 1) || forceFast) return fastResults;
+  const { semanticSearch } = await import('../core/search.mjs');
+  return semanticSearch(query, { ...options, rankResults });
+}
 
 function printHelp() {
   console.log(`
@@ -20,8 +37,18 @@ function printHelp() {
     --fast                     Force frontmatter-only search without semantic fallback
     --local                    Search indexed body text without a provider (default)
     --semantic                 Opt into semantic enrichment
+    --field                    Re-rank candidates with the compiled field (opt-in, local)
+    --compile-field            Compile existing embeddings into the selected brain's field
+    --evaluate-field <file>     Compare local recall with/without field on fixed JSON queries
     --timings                  Print local stage timings on stderr
 
+  Field operations (support --project/--global, --top-k, --format):
+    total-recall recall --compile-field --project
+    total-recall recall --evaluate-field queries.json --project --format json
+    Query file: [{ "query": "search terms", "relevant": ["expected-slug"] }]
+    Overlap@k = shared slugs / k. Hit rate@k = queries with a relevant slug / queries.
+    Evaluation does not record access. It uses local recall and requires a compiled field.
+
   Examples:
     npx total-recall recall "Never run tsc directly"
     npx total-recall recall "Express server port" --top-k 3
@@ -55,6 +82,7 @@ export default async function recall(args) {
   let forceFast = false;
   let semantic = false;
   let timings = false;
+  let field = false;
 
   for (let i = 1; i < remainingArgs.length; i++) {
     const arg = remainingArgs[i];
@@ -111,8 +139,11 @@ export default async function recall(args) {
       semantic = false;
     } else if (arg === '--timings') {
       timings = true;
+    } else if (arg === '--field') {
+      field = true;
     }
   }
+  top_k = Math.max(1, Math.min(20, top_k));
 
   // Determine which brains to search
   const brains = getBothBrains();
@@ -152,6 +183,26 @@ export default async function recall(args) {
   }
 
   try {
+    if (query === '--compile-field' || query === '--evaluate-field') {
+      const reports = [];
+      const cases = query === '--evaluate-field'
+        ? JSON.parse(fs.readFileSync(remainingArgs[1], 'utf8')) : null;
+      for (const target of searchTargets) {
+        const options = { vaultDir: path.join(target.brainDir, 'memory-vault'),
+          derivedDir: path.join(target.brainDir, 'memory-derived'), top_k, includeSessions: false };
+        if (query === '--evaluate-field') {
+          const { evaluateField } = await import('../core/field-evaluation.mjs');
+          reports.push({ brain: target.label, ...await evaluateField(cases, {
+            topK: top_k, search: (q, enabled) => searchRecallBrain(q, { ...options, field: enabled }),
+          }) });
+        } else {
+          const { compileField } = await import('../core/vector-field.mjs');
+          reports.push({ brain: target.label, ...(await compileField(options)).meta });
+        }
+      }
+      console.log(JSON.stringify(reports, null, 2));
+      return;
+    }
     // Search all target brains and merge results
     let allResults = [];
     let isDegraded = false;
@@ -164,8 +215,7 @@ export default async function recall(args) {
 
       try {
         let results = [];
-        const { fastSearch } = await import('../core/fast-recall.mjs');
-        const fastResults = fastSearch(query, {
+        results = await searchRecallBrain(query, {
           derivedDir,
           vaultDir,
           top_k,
@@ -174,28 +224,12 @@ export default async function recall(args) {
           modality,
           importance,
           priority,
-          fullText: !forceFast,
+          forceFast, semantic, field,
+          includeSessions: includeSessions && target.label !== 'global',
         });
-        if (timings) console.error(JSON.stringify({ brain: target.label, ...fastResults.stats }));
-        if (['missing', 'corrupt', 'metadata-only'].includes(fastResults.stats.index) && !forceFast) {
-          console.error(`Local full-text index for ${target.label}: ${fastResults.stats.index}. Run total-recall compile to rebuild; available metadata results may be incomplete.`);
-        }
-
-        if (!semantic || fastResults.some(result => result.score === 1) || forceFast) {
-          results = fastResults;
-        } else {
-          const { semanticSearch } = await import('../core/search.mjs');
-          results = await semanticSearch(query, {
-            vaultDir,
-            derivedDir,
-            top_k,
-            includeSessions: includeSessions && target.label !== 'global', // sessions only in project/local
-            category,
-            tags,
-            modality,
-            importance,
-            priority
-          });
+        if (timings) console.error(JSON.stringify({ brain: target.label, ...results.stats }));
+        if (['missing', 'corrupt', 'metadata-only'].includes(results.stats?.index) && !forceFast) {
+          console.error(`Local full-text index for ${target.label}: ${results.stats.index}. Run total-recall compile to rebuild; available metadata results may be incomplete.`);
         }
         if (results.degradedTextSearch) {
           isDegraded = true;
@@ -226,6 +260,15 @@ export default async function recall(args) {
     allResults.sort((a, b) => (b.score || 0) - (a.score || 0));
     allResults = allResults.slice(0, top_k);
 
+    // DECAY-01: a recalled memory is a used memory; record it in the brain it came from.
+    try {
+      const { recordAccess } = await import('../core/access-ledger.mjs');
+      for (const target of searchTargets) {
+        const slugs = allResults.filter(r => r._layer === target.label).map(r => r.slug || r.id).filter(Boolean);
+        recordAccess(path.join(target.brainDir, 'memory-derived'), slugs);
+      }
+    } catch { /* access accounting never breaks recall */ }
+
     if (format === 'json') {
       for (const error of searchErrors) console.error(`Search failed for ${error.label}: ${error.message.split('\n')[0]}`);
       if (searchErrors.length && !allResults.length) process.exitCode = 1;

package/src/cli/release.mjs

@@ -141,7 +141,10 @@ export async function tarballServed(pkg, version, { exec = spawnSync, fetchImpl
  * Wait until a just-published version can be installed: listed as latest, and its tarball served.
  * 3.42.0 took about six minutes and 3.42.1 about eight, its listing four minutes ahead of its tarball.
  */
-export async function awaitPublished(pkg, version, { attempts = 45, delayMs = 20000, exec = spawnSync, sleep, tarball = tarballServed } = {}) {
+/** npm has taken 8 and then 23 minutes to serve an accepted publish, so a shorter wait reports failure on a good release. */
+export const REGISTRY_WAIT = Object.freeze({ attempts: 120, delayMs: 20000 });
+
+export async function awaitPublished(pkg, version, { attempts = REGISTRY_WAIT.attempts, delayMs = REGISTRY_WAIT.delayMs, exec = spawnSync, sleep, tarball = tarballServed } = {}) {
   const pause = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
   let last = null;
   for (let i = 0; i < attempts; i++) {

package/src/cli/remember.mjs

@@ -37,6 +37,7 @@ function printHelp() {
     --object <string>         SPO Object (default: brain)
     --related <list>          Comma-separated list of related slugs
     --expires <duration>       TTL for temporary rules (e.g. "7d", "2w", "30d", "6h", "3m")
+    --allow-long              Permit a rule above 800 characters (context:policy also permits it)
     --confined-fact            Create a descriptive fact with generated identity; refresh local search without executable generators
 
   Examples:
@@ -74,9 +75,6 @@ function parseDuration(str) {
   return date;
 }
 
-const RULE_SOFT_LIMIT = 300;
-const RULE_HARD_LIMIT = 800;
-
 export default async function remember(args) {
   // Parse layer flag first
   const { layer: explicitLayer, remainingArgs: layerArgs } = parseLayerFlag(args);
@@ -244,16 +242,6 @@ export default async function remember(args) {
     }
   }
 
-  // Rules load into every task capsule, so they must be brief.
-  if (['invariants', 'preferences', 'anti-patterns'].includes(category) && !tags.includes('context:policy')) {
-    const n = bodyContent.trim().length;
-    if (n > RULE_HARD_LIMIT && !allowLong) {
-      console.error(`❌ Rule is ${n} characters (limit ${RULE_HARD_LIMIT}). Rules must be brief: one or two sentences, no history, dates, quotes or incident detail (save those as a fact). Shorten it, or pass --allow-long.`);
-      process.exit(1);
-    }
-    if (n > RULE_SOFT_LIMIT) console.error(`⚠️  Rule is ${n} characters. Keep rules brief (under ${RULE_SOFT_LIMIT}): state the constraint only, move history and examples to a fact. Shorten with: total-recall edit <slug> "<shorter>"`);
-  }
-
   const resolvedAgentDir = resolveAgentDir(layer);
   const resolvedBrainDir = resolveBrainDir(layer);
   const skillsDir = path.join(resolvedAgentDir, 'skills');
@@ -344,7 +332,7 @@ export default async function remember(args) {
 
   // Saving memory never optimizes or archives other canonical documents.
 
-  const vaultResult = await writeNodeValidatedAsync(node, vaultDir);
+  const vaultResult = await writeNodeValidatedAsync(node, vaultDir, { allowLong });
   if (!vaultResult.success) {
     console.error(`  ❌ Validation failed: ${vaultResult.validation.errors.join('; ')}`);
     if (vaultResult.repair) {
@@ -355,6 +343,7 @@ export default async function remember(args) {
     }
     process.exit(1);
   }
+  for (const warning of vaultResult.validation?.warnings || []) console.error(`  ⚠️  ${warning}`);
   console.log(`  ✅ Permanent SSSS memory node created ${layerLabel} in vault: memory-vault/${category}/${finalSlug}.md`);
 
   // Automatically recompile surfaces and local indexes

package/src/cli/server.mjs

@@ -0,0 +1,18 @@
+import { ensureServerService } from '../core/server-service.mjs';
+
+export default async function server(args = []) {
+  if (!args.length || args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: total-recall server ensure [--dry-run]\nRepair this package\'s macOS LaunchAgent and verify its process. --dry-run prints the plist diff without changes. On systemd hosts, server-release owns the server.');
+    return;
+  }
+  if (args[0] !== 'ensure' || args.slice(1).some(arg => arg !== '--dry-run')) {
+    console.error('Usage: total-recall server ensure [--dry-run]');
+    process.exitCode = 2;
+    return;
+  }
+  try {
+    const result = await ensureServerService({ dryRun: args.includes('--dry-run') });
+    console.log(result.diff || result.reason || `Server verified: pid ${result.pid}, ${result.entry}`);
+    return result;
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/src/cli/startup.mjs

@@ -36,6 +36,7 @@ export default async function startup(args = []) {
   if (args.includes('--json')) console.log(JSON.stringify(report, null, 2));
   else {
     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'}`);
+    if (report.server?.reason) console.log(`Server: ${report.server.reason}`);
     if (report.server?.stale) console.log(`Server: running ${report.server.stale.running} with ${report.server.stale.on_disk} on disk; it has not been replaced.`);
     for (const error of report.required_plugins?.errors || []) console.log(`Required plugin: ${error}`);
     const harnesses = await queryHarnessUsage().catch(() => []);

package/src/cli/task.mjs

@@ -34,10 +34,11 @@ function printHelp() {
     show <slug>        Show one task
     cancel <slug>      Cancel a task, optionally with --expected-status pending
     executors          List registered executor ids
+    idle               Enqueue leader maintenance from an automations manifest task
 
   add options:
     --kind <k>         memory | research | maintenance | system | custom (default: custom)
-    --executor <id>    dream | custom | research | session-ingest | surface-compile | prune
+    --executor <id>    dream | custom | research | legacy
     --priority <p>     high | normal | low | absolute | 0-100 (default: normal)
     --cap <list>       Comma-separated capabilities (default: vault:read)
                        Use vault:write to draft results into memory-inbox
@@ -58,7 +59,7 @@ function printHelp() {
 
   Policy:
     shell / net:post capabilities are denied by default.
-    Proactive idle fill is off unless TR_IDLE_TASKS=1.
+    Empty queues stay empty. Automations owns the idle schedule.
 `);
 }
 
@@ -168,6 +169,12 @@ export default async function taskCli(argv) {
   const brainDir = resolveBrainDir(layer);
   const queueDir = resolveQueueDir(brainDir);
 
+  if (opts.command === 'idle') {
+    const { enqueueScheduledIdleTasks } = await import('../core/scheduler.mjs');
+    console.log(JSON.stringify(await enqueueScheduledIdleTasks({ queueDir, vaultDir: path.join(brainDir, 'memory-vault') })));
+    return;
+  }
+
   if (opts.command === 'executors') {
     console.log('\n  Registered executors:\n');
     for (const id of listExecutorIds()) {

package/src/cli/update.mjs

@@ -50,6 +50,7 @@ export function parseArgs(args) {
     else if (a === '--port' && args[i + 1]) opts.port = Number(args[++i]);
     else if (a === '--no-build') opts.noBuild = true;
     else if (a === '--all-brains') opts.allBrains = true;
+    else if (a === '--install-missing') opts.installMissing = true;
     else if (a === '--json') opts.json = true;
     else if (a === '--automatic') opts.automatic = true;
     else if (a === '--status') opts.status = true;
@@ -70,16 +71,20 @@ function printHelp() {
     total-recall update --apply --force Ignore throttle / disabled flag
     total-recall update --repo <path>   Include extra root (repeatable)
     total-recall update --all-brains    Plan SSSS + Total Recall updates, including plugins/nested packages
-    total-recall update --all-brains --apply [--json]
+    total-recall update --all-brains --apply [--install-missing] [--json]
         Pin the same published versions, use npm/pnpm, replace shared dependency
         links with independent local installs, and verify every resolved version.
+        A checkout with no node_modules keeps none: only its pin is updated.
+        --install-missing installs those trees too (never done automatically).
         A plugin checkout linked into a brain but not registered as a project is
         only installed here: its dev dependencies are skipped (it runs under the
         shared install) and its runtime ones update with --omit=dev, without
         writing package.json or the lockfile. Register it to develop it here.
     total-recall update --automatic [--json]
         Daemon maintenance: update both packages, ensure defaults, update every
-        installed plugin from its recorded source and refresh surfaces.
+        installed plugin from its recorded source and refresh surfaces. Where a
+        per-user service (LaunchAgent, systemd user unit) runs the server from
+        the global install, also restart a stale server and verify /health.
     total-recall update --status [--json]
         Read the actual last automatic maintenance report without starting work.
         Also reports what the server on this host runs against the release.
@@ -96,6 +101,7 @@ function printHelp() {
 
   Env:
     TR_AUTO_UPDATE_PACKAGE=0   Disable daemon cron auto-update (default: on)
+    TR_SERVER_AUTO_RESTART=0   Report a stale server instead of restarting it (default: on)
     TR_SYNC_REPOS=/a:/b       Extra project roots
 
   Source monorepos named ${PACKAGE_NAME} are skipped (use git, not npm into self).
@@ -124,7 +130,7 @@ export default async function update(args = []) {
 
   if (opts.allBrains) {
     const summary = await updateAllBrains({ brainDir, roots: opts.repos,
-      dryRun: !opts.apply || opts.dryRun, ensureDefaults: true });
+      dryRun: !opts.apply || opts.dryRun, ensureDefaults: true, installMissing: opts.installMissing === true });
     if (summary.failed) process.exitCode = 1;
     if (opts.apply && !opts.dryRun) {
       const hooks = await installHarnessHooks({ log: (line) => { if (!opts.json) console.log(line); } });
@@ -134,6 +140,7 @@ export default async function update(args = []) {
     if (opts.json) console.log(JSON.stringify(summary, null, 2));
     else {
       console.log(`\n  Uniform brain updates: ${summary.consumer_count || 0} consumers`);
+      console.log(`  Missing: ${summary.not_installed || 0}; current: ${summary.up_to_date || 0}; would update: ${summary.would_update || 0}; updated: ${summary.updated || 0}; failed: ${summary.failed || 0}`);
       if (summary.reason) console.log(`  ${summary.reason}`);
       for (const row of summary.results) {
         console.log(`  ${row.root}: ${row.status}`);

package/src/core/access-ledger.mjs

@@ -0,0 +1,78 @@
+/**
+ * Memory access ledger (DECAY-01).
+ *
+ * Records when a memory is actually used: returned by recall or included in a context
+ * capsule. Decay reads it to tell a memory nobody uses from one read every day. It lives in
+ * the brain's derived state, so a read never rewrites a vault file.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicWrite } from './vault.mjs';
+
+const LEDGER = 'access-ledger.json';
+
+function ledgerFile(derivedDir) {
+  return path.join(derivedDir, LEDGER);
+}
+
+/** The ledger as `{ slug: { last_accessed, count } }`. A missing or damaged file is an empty ledger. */
+export function readAccess(derivedDir) {
+  if (!derivedDir) return {};
+  try {
+    const value = JSON.parse(fs.readFileSync(ledgerFile(derivedDir), 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Reserved ledger key: the days on which this brain was used at all (YYYY-MM-DD, sorted). */
+export const ACTIVE_DAYS = '_active_days';
+
+/** The days this brain was used, oldest first. */
+export function activeDays(ledger = {}) {
+  return Array.isArray(ledger[ACTIVE_DAYS]) ? ledger[ACTIVE_DAYS] : [];
+}
+
+/**
+ * How many of the brain's active days came after `sinceMs`. Decay counts these, never calendar
+ * days, so a brain nobody works in never decays (Greg, 2026-11-09).
+ */
+export function activeDaysSince(ledger, sinceMs) {
+  const since = new Date(sinceMs).toISOString().slice(0, 10);
+  return activeDays(ledger).filter(day => day > since).length;
+}
+
+/** Record one use of each slug, and today as an active day. Never throws: a failed write must not break recall or preflight. */
+export function recordAccess(derivedDir, slugs, now = new Date()) {
+  const unique = [...new Set((slugs || []).filter(slug => typeof slug === 'string' && slug && slug !== ACTIVE_DAYS))];
+  if (!derivedDir || unique.length === 0) return false;
+  try {
+    const ledger = readAccess(derivedDir);
+    const stamp = now.toISOString();
+    const today = stamp.slice(0, 10);
+    const days = activeDays(ledger);
+    if (!days.includes(today)) ledger[ACTIVE_DAYS] = [...days, today].sort();
+    for (const slug of unique) {
+      const entry = ledger[slug] || { count: 0 };
+      // Three active days are enough for the field's first and second derivatives.
+      const daily = { ...entry.daily_counts, [today]: (Number(entry.daily_counts?.[today]) || 0) + 1 };
+      const recentDays = activeDays(ledger).slice(-3);
+      ledger[slug] = { last_accessed: stamp, count: (Number(entry.count) || 0) + 1,
+        daily_counts: Object.fromEntries(Object.entries(daily).filter(([day]) => recentDays.includes(day))) };
+    }
+    fs.mkdirSync(derivedDir, { recursive: true });
+    atomicWrite(ledgerFile(derivedDir), JSON.stringify(ledger));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The latest known use of a memory: the ledger, its own `last_accessed`, or its last update. */
+export function lastUsedMs(node, ledger = {}) {
+  const times = [ledger[node.slug]?.last_accessed, node.last_accessed, node.updated, node.created]
+    .map(value => new Date(value || 0).getTime())
+    .filter(Number.isFinite);
+  return times.length ? Math.max(...times) : 0;
+}

package/src/core/agent-manager.mjs

@@ -1,11 +1,11 @@
-/** Compatibility facade; process lifecycle, isolation, metadata and receipts belong to Meta Harness. */
+/** Compatibility facade; process lifecycle, isolation, metadata and receipts belong to Metaharness. */
 import { loadPluginModule } from './plugin-runtime.mjs';
 
 let owner, ownerError;
 try { owner = await loadPluginModule('meta-harness', 'process-manager'); }
 catch (error) { ownerError = error; }
 function implementation() {
-  if (!owner) throw new Error(`Meta Harness processes are unavailable: ${ownerError?.message || 'install the plugin'}`);
+  if (!owner) throw new Error(`Metaharness processes are unavailable: ${ownerError?.message || 'install the plugin'}`);
   return owner;
 }
 export const loadAgentState = (...args) => implementation().loadAgentState(...args);

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

@@ -13,6 +13,7 @@ import { updateMeshBrainPackages } from './mesh-brain-updates.mjs';
 import { updateSourceBrainPackages } from './source-brain-updates.mjs';
 import { updateInstalledPlugins } from './plugin-updates.mjs';
 import { runningServerStatus } from './running-server.mjs';
+import { replaceStaleServer } from './server-restart.mjs';
 
 export function automaticUpdateStatus(brainDir) {
   let last;
@@ -37,7 +38,7 @@ export function startAutomaticBrainUpdates({brainDir,intervalMs=60*60*1000,run=r
   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,pluginUpdate=updateInstalledPlugins,skillMaintenance=maintainPortableSkills,serverCheck=runningServerStatus,now=Date.now}={}) {
+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,pluginUpdate=updateInstalledPlugins,skillMaintenance=maintainPortableSkills,serverCheck=runningServerStatus,replaceServer=replaceStaleServer,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{}
@@ -65,16 +66,20 @@ export async function runAutomaticBrainUpdates({brainDir,fleet=false,force=false
       const plugins=await pluginUpdate({roots:[path.resolve(brainDir,'../../..')]});
       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 || plugins.updated>0 || global.results.some(row=>row.status==='updated') || sources.results.some(row=>row.status==='updated') || JSON.stringify(saved?.versions)!==JSON.stringify(summary.versions);
-      // A lagging server is reported and not counted as a failure: maintenance cannot fix it, and
-      // a failure would retry every five minutes. Replacing one in production is a deploy decision.
-      const server=await serverCheck({brainDir,latest:summary.versions?.['total-recall-brain']});
-      if(server.status==='stale' || server.status==='down')logger.error('automatic-brain-updates',`Running server: ${server.reason}`);
       const skills=await skillMaintenance({brainDir});
       const surfaces=await compile({brainDir,force:changed || skills.updated > 0});
+      // Last, so a replaced server starts on everything this run moved. Where maintenance cannot
+      // replace it, a lagging server is reported and not counted as a failure, which would retry
+      // every five minutes for nothing: in production that is a deploy decision. Where it can, a
+      // hold or a failed attempt is this machine's own failure, which is what makes a peer dispatch it again.
+      let server=await serverCheck({brainDir,latest:summary.versions?.['total-recall-brain']});
+      if(server.status==='stale')server=await replaceServer({brainDir,server,globalRoot:global.root,previous:saved?.server});
+      if(server.status==='stale' || server.status==='down')logger.error('automatic-brain-updates',`Running server: ${server.replacement?.reason || server.reason}`);
+      const serverFailed=['held','failed'].includes(server.replacement?.state)?1:0;
       // local_failed is this node's own maintenance. Peers judge a node by it, not by
       // `failed`, which also counts the node's view of its peers: judging by that made
       // every fleet pass mark every peer failed forever, each because the others had.
-      const local_failed=(summary.failed || 0)+global.failed+sources.failed+plugins.failed+(skills.failed || 0)+(surfaces.ok?0:surfaces.results.filter(row=>row.status==='failed').length);
+      const local_failed=(summary.failed || 0)+global.failed+sources.failed+plugins.failed+(skills.failed || 0)+(surfaces.ok?0:surfaces.results.filter(row=>row.status==='failed').length)+serverFailed;
       report={...summary,global,sources,plugins,mesh,server,skills,surfaces,local_failed,failed:local_failed+mesh.failed,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);