total-recall-brain 3.43.3 → 3.45.0

package/src/core/lessons.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomicWrite } from './vault.mjs';
+import { addTask, getTask, resolveQueueDir } from './task-envelope.mjs';
+import { readLessonEntries, countLessonTurns, selectLessonTurns } from './lesson-sessions.mjs';
+import { acquireBrainUpdateLock } from './brain-updates.mjs';
+
+export const DEFAULT_LESSON_INTERVAL = 10;
+const hash = value => crypto.createHash('sha256').update(value).digest('hex').slice(0, 12);
+
+/** A local hook only queues work. It never calls a model or elects a leader. */
+export function tickLessons({ brainDir, sessionId, transcriptPath, event = 'Stop', interval,
+  turnId, turnCount, harness = 'unknown', hold } = {}) {
+  if (!brainDir || !sessionId) throw new Error('Lesson review requires a brain and session id');
+  const sessionsDir = path.join(brainDir, 'sessions');
+  const configPath = path.join(brainDir, 'config', 'lessons.json');
+  if (fs.existsSync(configPath)) {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (config.enabled === false) return { tasks: [], skipped: 'disabled' };
+    interval ??= config.interval;
+    if (hold === undefined) hold = config.holdWrites === true;
+  }
+  interval ??= DEFAULT_LESSON_INTERVAL;
+  if (!Number.isInteger(interval) || interval < 1) throw new Error('Lesson interval must be a positive integer');
+  hold ??= false;
+  const root = path.join(brainDir, 'lesson-reviews');
+  fs.mkdirSync(root, { recursive: true });
+  // Match writeSession's identity so native hooks and later ingest share a cursor.
+  const localTranscript = transcriptPath && path.dirname(path.resolve(transcriptPath)) === path.resolve(sessionsDir);
+  const key = transcriptPath ? (localTranscript ? path.basename(transcriptPath, '.jsonl') : hash(path.resolve(transcriptPath))) : hash(`${harness}:${sessionId}`);
+  const lock = path.join(root, `${key}.lock`);
+  const lockFd = acquireBrainUpdateLock(lock, { waitMs: 0 });
+  try {
+    const stateFile = path.join(root, `${key}.json`);
+    const state = fs.existsSync(stateFile) ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : { turns: 0, queuedThrough: 0 };
+    let entries;
+    const savedTranscript = path.join(sessionsDir, `${key}.jsonl`);
+    if (!transcriptPath && fs.existsSync(savedTranscript)) transcriptPath = savedTranscript;
+    if (transcriptPath) {
+      entries = readLessonEntries(transcriptPath);
+      turnCount = countLessonTurns(entries);
+      if (!localTranscript) {
+        fs.mkdirSync(sessionsDir, { recursive: true });
+        atomicWrite(path.join(sessionsDir, `${key}.jsonl`), entries.map(entry => JSON.stringify(entry)).join('\n') + '\n');
+      }
+    }
+    if (turnCount !== undefined) {
+      if (!Number.isInteger(turnCount) || turnCount < state.turns) throw new Error('Lesson transcript turn count went backwards');
+      state.turns = turnCount;
+    } else if (event === 'UserPromptSubmit' && (!turnId || turnId !== state.lastTurnId)) {
+      state.turns++;
+      state.lastTurnId = turnId;
+    }
+    const final = event === 'SessionEnd' || event === 'session-end';
+    const tasks = [];
+    // Prompt hooks count only. Stop has the completed response and tool results.
+    if (event !== 'UserPromptSubmit' && entries) {
+      while (state.turns - state.queuedThrough >= interval || (final && state.turns > state.queuedThrough)) {
+        const fromTurn = state.queuedThrough + 1;
+        const toTurn = Math.min(state.turns, state.queuedThrough + interval);
+        const slug = `lesson-review-${key}-${fromTurn}-${toTurn}`;
+        const queueDir = resolveQueueDir(brainDir);
+        if (!getTask(queueDir, slug) && !fs.existsSync(path.join(root, `${slug}.done`))) {
+          const snapshot = path.join(root, `${slug}.jsonl`);
+          atomicWrite(snapshot, selectLessonTurns(entries, { fromTurn, toTurn }).map(entry => JSON.stringify(entry)).join('\n') + '\n');
+          addTask({ slug, intent: `Review session ${sessionId}, turns ${fromTurn}–${toTurn}`,
+            kind: 'memory', executor: 'lesson-review', category: 'lesson-review', priority: 40,
+            origin: { agent: harness, session_id: sessionId },
+            payload: { sessionPath: snapshot, fromTurn, toTurn, hold, sessionId },
+          }, queueDir);
+        }
+        tasks.push(slug);
+        state.queuedThrough = toTurn;
+      }
+    }
+    atomicWrite(stateFile, JSON.stringify(state));
+    return { turns: state.turns, queuedThrough: state.queuedThrough, tasks };
+  } finally {
+    // Remove only the inode this process acquired. A dead hook's lock is reclaimed
+    // by the shared lock owner on the next tick.
+    try { if (fs.statSync(lock).ino === fs.fstatSync(lockFd).ino) fs.unlinkSync(lock); }
+    finally { fs.closeSync(lockFd); }
+  }
+}
+
+/** Session-ingest fallback for harnesses without a lifecycle hook. Every node calls this. */
+export function enqueueSessionReviews({ brainDir, now = Date.now(), quietMs = 5 * 60_000, interval, hold } = {}) {
+  const dir = path.join(brainDir, 'sessions');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(name => name.endsWith('.jsonl')).map(name => {
+    const transcriptPath = path.join(dir, name);
+    return tickLessons({ brainDir, sessionId: path.basename(name, '.jsonl'), transcriptPath, interval, hold,
+      event: now - fs.statSync(transcriptPath).mtimeMs >= quietMs ? 'SessionEnd' : 'Stop', harness: 'session-ingest' });
+  });
+}

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

@@ -30,7 +30,8 @@ export async function updateMeshBrainPackages({version,versions,listNodes,exec,n
       let report,serving;try{const status=JSON.parse(observed.stdout);report=status.last;serving=status.server;}catch{}
       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']);
-      // Maintenance cannot fix a lagging server, so this is reported and not dispatched again.
+      // Maintenance could not fix this server, or it would have reported a local failure above and
+      // been dispatched again, so this is reported. One that lags since the last run waits for that run's report to age.
       if(current && serving?.status==='stale'){row.status='failed';row.report=report;row.server=serving;row.error=serving.reason;continue;}
       if(current){row.status='verified';row.report=report;continue;}
       // npm exec pins the verified release so an old installed CLI can bootstrap

package/src/core/meta-harness.mjs

@@ -1,11 +1,11 @@
-/** Compatibility facade only. Adapter contracts, auth, usage and execution belong to Meta Harness. */
+/** Compatibility facade only. Adapter contracts, auth, usage and execution belong to Metaharness. */
 import { loadPluginModule } from './plugin-runtime.mjs';
 
 let owner, ownerError;
 try { owner = await loadPluginModule('meta-harness', 'harness-compat'); }
 catch (error) { ownerError = error; }
 function implementation() {
-  if (!owner) throw new Error(`Meta Harness is unavailable: ${ownerError?.message || 'install the plugin'}`);
+  if (!owner) throw new Error(`Metaharness is unavailable: ${ownerError?.message || 'install the plugin'}`);
   return owner;
 }
 

package/src/core/optimizer.mjs

@@ -4,8 +4,8 @@ import crypto from 'crypto';
 import matter from './frontmatter.mjs';
 import { writeNode } from './vault.mjs';
 import { getNodes } from './vault-cache.mjs';
+import { readAccess, lastUsedMs, activeDaysSince } from './access-ledger.mjs';
 import { logger } from './logger.mjs';
-import { brainDir } from './config.mjs';
 
 /**
  * Total Recall Optimizer
@@ -166,129 +166,6 @@ export async function generateMemoryCleanupProposals(vaultDir) {
   return proposals;
 }
 
-/**
- * Scans skill execution logs (if available) and proposes improvements.
- */
-/**
- * Scan skill files for quality issues and propose improvements.
- * Looks at skill files that haven't been updated in >30 days and
- * checks for common issues: missing examples, vague instructions, outdated commands.
- */
-export async function generateSkillImprovementProposals(vaultDir) {
-  const agentDir = path.join(path.dirname(vaultDir));
-  const skillsDir = path.join(agentDir, 'skills');
-  const proposals = [];
-
-  if (!fs.existsSync(skillsDir)) return proposals;
-
-  const now = Date.now();
-  const staleCutoff = 30 * 24 * 60 * 60 * 1000; // 30 days
-
-  try {
-    const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
-      .filter(d => d.isDirectory())
-      .map(d => path.join(skillsDir, d.name, 'SKILL.md'))
-      .filter(p => fs.existsSync(p));
-
-    for (const skillFile of skillDirs) {
-      const stat = fs.statSync(skillFile);
-      const ageMs = now - stat.mtimeMs;
-      if (ageMs < staleCutoff) continue;
-
-      const raw = fs.readFileSync(skillFile, 'utf8');
-      const hasExamples = /##\s*example/i.test(raw);
-      const hasCaution = /caution|warning|never|must not/i.test(raw);
-      const lineCount = raw.split('\n').length;
-
-      const issues = [];
-      if (!hasExamples) issues.push('No examples section');
-      if (!hasCaution) issues.push('No caution/constraint section');
-      if (lineCount < 20) issues.push('Very short — may lack detail');
-
-      if (issues.length > 0) {
-        const skillName = path.basename(path.dirname(skillFile));
-        proposals.push(createProposal(
-          'skill-improvement',
-          `Improve skill: ${skillName} (${issues.join(', ')})`,
-          skillFile,
-          `Skill file is ${Math.floor(ageMs / 86400000)} days old. Issues: ${issues.join('; ')}`,
-        ));
-      }
-    }
-  } catch (err) {
-    logger.debug('optimizer: generateSkillImprovementProposals failed to read skillsDir', { err: err.message });
-  }
-
-  return proposals;
-}
-
-/**
- * Scan the task queue for stuck or stalled workflows.
- * Tasks that have been 'in-progress' for >1 hour are considered stalled.
- */
-export async function generateWorkflowRepairProposals(vaultDir) {
-  const queueDir = path.join(brainDir, 'scheduler', 'queue');
-  const proposals = [];
-
-  if (!fs.existsSync(queueDir)) return proposals;
-
-  const now = Date.now();
-  const stalledCutoff = 60 * 60 * 1000; // 1 hour
-
-  try {
-    const files = fs.readdirSync(queueDir).filter(f => f.endsWith('.md'));
-    for (const file of files) {
-      const raw = fs.readFileSync(path.join(queueDir, file), 'utf8');
-      const { data } = matter(raw);
-      if (data.status !== 'in-progress') continue;
-
-      const updatedAt = new Date(data.updated_at || data.created || 0).getTime();
-      if (now - updatedAt < stalledCutoff) continue;
-
-      proposals.push(createProposal(
-        'workflow-repair',
-        `Stalled task: ${data.slug || file}`,
-        path.join(queueDir, file),
-        `Task has been in-progress for ${Math.floor((now - updatedAt) / 60000)} minutes. May need retry or cancellation.`,
-      ));
-    }
-  } catch (err) {
-    logger.debug('optimizer: generateWorkflowRepairProposals failed to read queueDir', { err: err.message });
-  }
-
-  return proposals;
-}
-
-/**
- * Analyze the vault's model usage patterns and propose routing improvements.
- * Flags cases where high-priority tasks were sent to the local LLM
- * that should have used a frontier model.
- */
-export async function generateModelRoutingProposals(vaultDir) {
-  const proposals = [];
-  const nodes = getNodes(vaultDir);
-
-  // Find high-importance facts with low confidence — likely needed frontier model
-  const underconfident = nodes.filter(n =>
-    n.status === 'active' &&
-    n.category === 'facts' &&
-    n.importance >= 4 &&
-    n.confidence < 0.6 &&
-    n.source?.agent === 'fact-seeker',
-  );
-
-  for (const node of underconfident.slice(0, 5)) {
-    proposals.push(createProposal(
-      'model-routing',
-      `Re-research with frontier model: "${node.title}"`,
-      node.slug,
-      `High-importance fact (importance: ${node.importance}) has low confidence (${node.confidence}). Originally researched by local model. Frontier model may produce better synthesis.`,
-    ));
-  }
-
-  return proposals;
-}
-
 /**
  * Nodes that are important but have gone untouched — computed on demand.
  *
@@ -310,21 +187,6 @@ export function findStaleNodes(vaultDir, { days = 30, minImportance = 4 } = {})
     .sort((a, b) => new Date(a.last_accessed) - new Date(b.last_accessed));
 }
 
-/**
- * @deprecated Wrote tickets nothing reads. Retained because the dream cycle's
- * master switch (ENABLE_STALE_KNOWLEDGE_REFRESH, off) still references it.
- * Stale nodes are surfaced to a human via findStaleNodes instead; nothing
- * re-researches them automatically (RESEARCH_SYSTEM2).
- */
-export async function generateStaleKnowledgeRefreshProposals(vaultDir) {
-  return findStaleNodes(vaultDir, { days: 30, minImportance: 4 }).map(node => createProposal(
-    'stale-knowledge-refresh',
-    `Refresh stale high-importance memory: ${node.title}`,
-    node.slug,
-    'Node has not been accessed in over 30 days but maintains high importance. Requires verification against current state.',
-  ));
-}
-
 /**
  * Local Eval Gate for Proposal Promotion
  * Uses the local runtime to evaluate the validity of a proposal.
@@ -379,6 +241,14 @@ export async function evaluateProposalGate(proposal, runtimeConfig, vaultDir = n
     return stamp('accepted');
   }
 
+  // smart-decay is verified mechanically against live state: the memory still exists, is
+  // active and unprotected, and the access ledger shows no use since it was judged and for
+  // the full decay age. Only then may it reach `accepted` and auto-apply (DECAY-01).
+  if (proposal.category === 'smart-decay') {
+    const reason = verifySmartDecay(proposal, vaultDir);
+    return reason ? stamp('rejected', { rejection_reason: reason }) : stamp('accepted');
+  }
+
   // stale-knowledge-refresh no longer produces tickets at all — the work is
   // handed to the research queue, which can actually perform it. If one is
   // somehow generated, it is not something to auto-accept.
@@ -422,41 +292,67 @@ Output ONLY valid JSON.`;
  *
  * @param {string} vaultDir
  * @param {object} runtimeConfig
- * @param {number} [ageThresholdDays=60]  Minimum age before considering decay
+ * @param {number} [ageThresholdDays=60]  Active days of the brain without a use before considering decay
  * @returns {object[]} decay proposals
  */
-export async function runSmartDecay(vaultDir, runtimeConfig, ageThresholdDays = 60) {
-  const { callLocalRuntime } = await import('./runtime.mjs');
+/** Active days (days the brain was used), never calendar days: an idle brain never decays. */
+export const DECAY_AGE_DAYS = 60;
+
+/**
+ * Why a smart-decay proposal may not be applied, or null when live state supports it.
+ * Shared by the gate and the applier so both check the same facts.
+ */
+export function verifySmartDecay(proposal, vaultDir, { now = Date.now(), ageThresholdDays = DECAY_AGE_DAYS } = {}) {
+  if (!vaultDir) return 'No vault to verify against.';
+  const slug = String(proposal.target_path || '').trim();
+  const node = getNodes(vaultDir).find(n => n.slug === slug);
+  if (!node) return `Memory ${slug} no longer exists.`;
+  if (node.status !== 'active') return `Memory ${slug} is already ${node.status}.`;
+  if (isDecayProtected(node)) return `Memory ${slug} is protected from decay.`;
+  const ledger = readAccess(path.join(path.dirname(vaultDir), 'memory-derived'));
+  const used = lastUsedMs(node, ledger);
+  if (proposal.decay_last_used_at && used > new Date(proposal.decay_last_used_at).getTime()) return `Memory ${slug} was used after it was judged.`;
+  if (activeDaysSince(ledger, used) < ageThresholdDays) return `Memory ${slug} was used within the brain's last ${ageThresholdDays} active days.`;
+  return null;
+}
+
+/** Memories decay never touches: rules, absolute-priority and importance-5 memories. */
+export function isDecayProtected(node) {
+  return node.priority === 'absolute' || node.importance >= 5
+    || ['invariants', 'preferences', 'anti-patterns'].includes(node.category);
+}
+
+/** Active, unprotected memories unused for at least `ageThresholdDays` of the brain's active days. */
+export function decayCandidates(nodes, ledger, { now = Date.now(), ageThresholdDays = DECAY_AGE_DAYS } = {}) {
+  return nodes
+    .filter(n => n.status === 'active' && n.type !== 'proposal' && !isDecayProtected(n))
+    .filter(n => activeDaysSince(ledger, lastUsedMs(n, ledger)) >= ageThresholdDays)
+    .sort((a, b) => lastUsedMs(a, ledger) - lastUsedMs(b, ledger));
+}
+
+export async function runSmartDecay(vaultDir, runtimeConfig, ageThresholdDays = DECAY_AGE_DAYS, { derivedDir = path.join(path.dirname(vaultDir), 'memory-derived'), call } = {}) {
+  const callLocalRuntime = call || (await import('./runtime.mjs')).callLocalRuntime;
   const nodes = getNodes(vaultDir);
   const now = Date.now();
-  const ageThresholdMs = ageThresholdDays * 24 * 60 * 60 * 1000;
+  const ledger = readAccess(derivedDir);
   const proposals = [];
 
-  // Candidates: active, not absolute priority, not accessed recently
-  const candidates = nodes.filter(n => {
-    if (n.status !== 'active') return false;
-    if (n.priority === 'absolute') return false;
-    if (n.importance >= 5) return false;
-    const lastAccessed = new Date(n.last_accessed || n.updated || 0).getTime();
-    return (now - lastAccessed) > ageThresholdMs;
-  });
-
-  // Process up to 5 candidates per run to avoid excessive LLM calls
-  const batch = candidates.slice(0, 5);
+  // Oldest unused first, up to 5 per run to bound model calls.
+  const batch = decayCandidates(nodes, ledger, { now, ageThresholdDays }).slice(0, 5);
 
   for (const node of batch) {
-    const ageDays = Math.floor((now - new Date(node.last_accessed || node.updated || 0).getTime()) / (1000 * 60 * 60 * 24));
+    const ageDays = activeDaysSince(ledger, lastUsedMs(node, ledger));
 
     const prompt = [
       `## Memory Node: ${node.slug}`,
       `Title: "${node.title}"`,
-      `Category: ${node.category} | Importance: ${node.importance} | Age: ${ageDays} days`,
+      `Category: ${node.category} | Importance: ${node.importance} | Unused for ${ageDays} active days of its brain`,
       `Tags: ${(node.tags || []).join(', ')}`,
       '',
       '## Body',
       (node.body || '').slice(0, 800),
       '',
-      `This node has not been accessed in ${ageDays} days. Should it be retained, archived, or decayed?`,
+      `This node has not been used on the last ${ageDays} days its brain was active. Should it be retained, archived, or decayed?`,
     ].join('\n');
 
     try {
@@ -468,15 +364,20 @@ export async function runSmartDecay(vaultDir, runtimeConfig, ageThresholdDays =
       const verdict = result.verdict || 'RETAINED';
 
       if (verdict !== 'RETAINED') {
-        proposals.push(createProposal(
-          'smart-decay',
-          `Smart Decay [${verdict}]: "${node.title}"`,
-          node.slug,
-          `Age: ${ageDays} days. Reasoning: ${result.reasoning || 'No reasoning provided.'} Confidence adjustment: ${result.confidence_adjustment || 0}`,
-        ));
+        proposals.push({
+          ...createProposal(
+            'smart-decay',
+            `Smart Decay [${verdict}]: "${node.title}"`,
+            node.slug,
+            `Unused for ${ageDays} active days. Reasoning: ${result.reasoning || 'No reasoning provided.'} Confidence adjustment: ${result.confidence_adjustment || 0}`,
+          ),
+          // The gate re-checks that the memory has not been used since this judgement.
+          decay_verdict: verdict,
+          decay_last_used_at: new Date(lastUsedMs(node, ledger)).toISOString(),
+        });
       }
-    } catch {
-      // Skip failed evaluations silently
+    } catch (err) {
+      logger.warn('optimizer', `Smart decay could not evaluate ${node.slug}: ${err.message}`);
     }
   }
 

package/src/core/plugin-contracts/card.mjs

@@ -55,6 +55,9 @@ export function validateCardContract(manifest) {
       else names.add(sub.name);
       if (sub.effect !== undefined && !COMMAND_EFFECTS.includes(sub.effect)) errors.push(`${where}.effect must be one of: ${COMMAND_EFFECTS.join(', ')}`);
       if (sub.output !== undefined && !OUTPUT_KINDS.includes(sub.output)) errors.push(`${where}.output must be one of: ${OUTPUT_KINDS.join(', ')}`);
+      // The runner refuses anything outside this range, so a manifest that
+      // declares it must fail validation rather than every call at run time.
+      if (sub.timeout_ms !== undefined && (!Number.isInteger(sub.timeout_ms) || sub.timeout_ms < 1 || sub.timeout_ms > 600000)) errors.push(`${where}.timeout_ms must be an integer from 1 to 600000`);
       if (sub.args !== undefined) {
         if (!Array.isArray(sub.args)) errors.push(`${where}.args must be an array`);
         else {

package/src/core/plugin-loader.mjs

@@ -48,7 +48,7 @@ export function resolveProjectRoot(projectRoot, vaultDir) {
   return fs.existsSync(path.join(parent, '.agent')) ? parent : (projectRoot || process.cwd());
 }
 
-/** True when a 5-field cron expression is syntactically plausible. Semantics are checked by plugin-tasks. */
+/** True when a 5-field cron expression is syntactically plausible. The scheduling owner checks semantics. */
 export function isCronExpression(expr) {
   if (typeof expr !== 'string') return false;
   const fields = expr.trim().split(/\s+/);
@@ -277,6 +277,13 @@ export function validatePluginManifest(manifest) {
         if (!/^[a-z][a-z0-9-]*$/.test(name) || !isSafeRelativePath(file)) errors.push(`Invalid runtime module ${name}`);
       }
       if (runtime.routers !== undefined && (!Array.isArray(runtime.routers) || runtime.routers.some(file => !isSafeRelativePath(file)))) errors.push('runtime.routers must contain safe relative paths');
+      // Daemon services name declared runtime modules; the daemon starts each one.
+      if (runtime.daemon !== undefined) {
+        if (!Array.isArray(runtime.daemon)) errors.push('runtime.daemon must be an array of runtime module names');
+        else for (const name of runtime.daemon) {
+          if (typeof name !== 'string' || !Object.hasOwn(runtime.modules || {}, name)) errors.push(`runtime.daemon names undeclared module ${name}`);
+        }
+      }
     }
   }
 
@@ -411,9 +418,11 @@ export function discoverPlugins(projectRoot = process.cwd()) {
   const seen = new Set();
   const plugins = [];
   const global = globalPluginsDir();
-  const project = projectPluginsDir(projectRoot);
+  // Nothing is installed per repository: every plugin lives in the shared
+  // folder, and a repository only switches it on or off. A leftover repository
+  // plugin folder is never read (`plugin copies` reports and removes it).
+  // `projectRoot` stays in the signature for callers; discovery no longer depends on it.
   const sources = [
-    ...(path.resolve(project) === path.resolve(global) ? [] : [[project, 'project']]),
     [global, 'global'],
     [path.join(PACKAGE_ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins'), 'scaffold']
   ];

package/src/core/plugin-runtime.mjs

@@ -1,7 +1,45 @@
 /** Generic in-process extension loading. Domain behavior stays with its owner. */
+import os from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { discoverPlugins, resolvePluginFile, PACKAGE_ROOT } from './plugin-loader.mjs';
 import { pluginActivation } from './plugin-state.mjs';
+import { logger } from './logger.mjs';
+
+/**
+ * Start every daemon service an active plugin declares in `runtime.daemon`.
+ * Each named runtime module exports `start({ projectRoot })` and may return a
+ * stop function. Services run against the global brain (home), never the
+ * directory the daemon happens to start in. One failing service is logged and
+ * never stops the others.
+ * @returns {Promise<{ started: string[], failed: string[], stop: Function }>}
+ */
+export async function startPluginDaemonServices({ projectRoot = os.homedir(), load = loadPluginModule } = {}) {
+  const stops = [];
+  const started = [];
+  const failed = [];
+  for (const plugin of discoverPlugins(projectRoot).filter(item => item.valid)) {
+    const names = plugin.manifest.runtime?.daemon || [];
+    if (!names.length || !pluginActivation(plugin, { projectRoot }).enabled) continue;
+    for (const name of names) {
+      const label = `${plugin.id}:${name}`;
+      try {
+        const module = await load(plugin.id, name, { projectRoot, activeRequired: true });
+        if (typeof module.start !== 'function') throw new Error('daemon module must export start()');
+        const stop = await module.start({ projectRoot });
+        if (typeof stop === 'function') stops.push(stop);
+        started.push(label);
+      } catch (err) {
+        failed.push(label);
+        logger.warn('plugin-runtime', `Daemon service ${label} failed to start: ${err.message}`);
+      }
+    }
+  }
+  return {
+    started,
+    failed,
+    stop: () => { for (const stop of stops) { try { stop(); } catch { /* already stopped */ } } },
+  };
+}
 
 export async function loadPluginModule(id, name, { activeRequired = false, requireValid = true, projectRoot = process.cwd() } = {}) {
   const plugin = discoverPlugins(projectRoot).find(item => item.id === id);
@@ -18,7 +56,8 @@ export async function loadPluginModule(id, name, { activeRequired = false, requi
   }
   process.env.TR_PACKAGE_ROOT = PACKAGE_ROOT;
   const file = resolvePluginFile(plugin.dir, relative);
-  return import(process.platform === 'win32' ? pathToFileURL(file).href : file);
+  // A file URL is unambiguous on every platform and under every module loader.
+  return import(pathToFileURL(file).href);
 }
 
 export async function loadPluginRouters() {

package/src/core/plugin-store.mjs

@@ -340,6 +340,31 @@ export function isGitSource(source) {
 export async function recompileAfterPluginMutation(projectRoot = process.cwd(), isGlobal = false, dependencies = {}) {
   try {
     const { compileSurface } = dependencies.compileSurface ? dependencies : await import('./surface.mjs');
+    // Only this layer's catalog changes. Entry files are static and rules and commands are
+    // read on demand at preflight, so a shared plugin change compiles no other repository
+    // (ON-DEMAND-CONTEXT-01; one install used to rebuild all registered brains).
+    await compileLayer(compileSurface, projectRoot, isGlobal);
+    if (isGlobal) {
+      // The repository the command ran in refreshes its own catalog now, so its plugin library
+      // never lags the change. That compile is cheap: entry files and vault indexes keep their
+      // own triggers, so only the catalog and CLI index move.
+      const agentDir = path.dirname(path.dirname(path.dirname(globalPluginsDir())));
+      const projectBrain = path.dirname(projectPluginsDir(projectRoot));
+      if (path.resolve(projectRoot, '.agent') !== path.resolve(agentDir) && fs.existsSync(projectBrain)) {
+        await compileLayer(compileSurface, projectRoot, false);
+      }
+    }
+    return { ok: true, inventoryUpdated: true };
+  } catch (err) {
+    try {
+      const { logger } = await import('./logger.mjs');
+      logger.warn('plugin-store', `Automatic compilation after plugin change failed: ${err.message}`);
+    } catch {}
+    return { ok: false, error: err.message };
+  }
+}
+
+async function compileLayer(compileSurface, projectRoot, isGlobal) {
     // Match the actual destination chosen by install/remove, not an ambient brain override.
     const pluginsDir = isGlobal ? globalPluginsDir() : projectPluginsDir(projectRoot);
     const brainDir = path.dirname(pluginsDir);
@@ -359,19 +384,6 @@ export async function recompileAfterPluginMutation(projectRoot = process.cwd(),
     const instructionsFile = path.join(surfaceDir, 'INSTRUCTIONS.md');
     const result = await compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile, force: true, semantic: false });
     if (result.skipped && result.reason === 'stale-surface-code') throw new Error('Instruction compiler is stale; restart the host or run total-recall compile');
-    if (isGlobal) {
-      const { compileRegisteredProjects } = dependencies.compileRegisteredProjects ? dependencies : await import('../cli/rebuild.mjs');
-      const failed = await compileRegisteredProjects();
-      if (failed) throw new Error(`${failed} registered project surface compilation(s) failed`);
-    }
-    return { ok: true, inventoryUpdated: true };
-  } catch (err) {
-    try {
-      const { logger } = await import('./logger.mjs');
-      logger.warn('plugin-store', `Automatic compilation after plugin change failed: ${err.message}`);
-    } catch {}
-    return { ok: false, error: err.message };
-  }
 }
 
 /**
@@ -485,12 +497,16 @@ export function pruneReplacementArchives(archiveDir, { id, keep = 1, apply = tru
  * @param {{ projectRoot?: string, global?: boolean, link?: boolean, peerDeps?: object, publicDeps?: object }} [options]
  */
 export async function installPlugin(source, options = {}) {
-  const { projectRoot = process.cwd(), global: isGlobal = false, link = false, resolveBundle } = options;
+  const { projectRoot = process.cwd(), link = false, resolveBundle } = options;
   if (!source || typeof source !== 'string') throw new Error('Missing plugin source');
   source = source.trim();
+  // Nothing is installed per repository: every install goes to the shared
+  // folder, and a repository switches the plugin on or off with `plugin on|off`.
+  if (options.project === true) throw new Error("Plugins are installed only in the shared folder; a repository switches them with 'total-recall plugin on|off <id>'");
+  const isGlobal = true;
 
-  const scope = isGlobal ? 'global' : 'project';
-  const pluginsDir = isGlobal ? globalPluginsDir() : projectPluginsDir(projectRoot);
+  const scope = 'global';
+  const pluginsDir = globalPluginsDir();
 
   let manifest;
   let dest;
@@ -610,13 +626,9 @@ export async function installPlugin(source, options = {}) {
   }
 }
 
-export function findInstalled(id, { projectRoot = process.cwd(), global: isGlobal } = {}) {
-  const all = isGlobal === true ? [] : discoverPlugins(projectRoot);
-  if (isGlobal === true) {
-    // discoverPlugins() hides a global plugin shadowed by a project one.
-    return readPluginsDir(globalPluginsDir(), 'global').find((p) => p.id === id) || null;
-  }
-  return all.find((p) => p.id === id) || null;
+export function findInstalled(id) {
+  // Every install lives in the shared folder.
+  return readPluginsDir(globalPluginsDir(), 'global').find((p) => p.id === id) || null;
 }
 
 export async function uninstallPlugin(id, options = {}) {