total-recall-brain 3.44.0 → 3.45.0

package/src/core/server-service.mjs

@@ -0,0 +1,148 @@
+/** Repair this installation's macOS server LaunchAgent. Never manages systemd. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { processIdentity } from './startup-health.mjs';
+
+const PACKAGE_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+const LABEL = 'com.totalrecall.server';
+const corePathEnv = new Set(['AGENT_DIR', 'TR_SECRETS_BRAIN', 'TR_SERVER_PID_FILE']);
+const inside = (root, value) => value === root || value.startsWith(root + path.sep);
+const real = value => { try { return fs.realpathSync(value); } catch { return path.resolve(value); } };
+
+export function stableNodePath(env = process.env) {
+  for (const dir of (env.PATH || '').split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const candidate = path.join(dir, 'node');
+    if (candidate.split(path.sep).includes('Cellar')) continue;
+    try { fs.accessSync(candidate, fs.constants.X_OK); if (fs.statSync(candidate).isFile()) return candidate; } catch {}
+  }
+  throw new Error('No stable node executable on PATH. Add the node symlink directory to PATH.');
+}
+
+function convert(input, format, exec) {
+  const result = exec('plutil', ['-convert', format, '-o', '-', '-'], { input, encoding: 'utf8', timeout: 5000 });
+  if (result.status !== 0 || result.error) throw new Error(`Cannot convert server plist to ${format}.`);
+  return result.stdout;
+}
+
+/** Detect foreign installations without naming any operator repository. */
+function checkoutFor(value, oldRoot, packageRoot) {
+  if (inside(packageRoot, value) || inside(real(packageRoot), value)) return null;
+  if (oldRoot && real(oldRoot) !== real(packageRoot) && inside(oldRoot, value)) return oldRoot;
+  for (let dir = value; ; dir = path.dirname(dir)) {
+    try {
+      if (JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).name === 'total-recall-brain'
+          && real(dir) !== real(packageRoot)) return dir;
+    } catch {}
+    if (dir === path.dirname(dir)) return null;
+  }
+}
+
+export function serverEnvironment(existing, { packageRoot, oldRoot }) {
+  const env = {};
+  for (const [key, value] of Object.entries(existing || {})) {
+    if (typeof value !== 'string') throw new Error(`Server environment ${key} must be a string.`);
+    if (key === 'PATH') {
+      env[key] = value.split(path.delimiter).map(part => {
+        const foreign = path.isAbsolute(part) && checkoutFor(part, oldRoot, packageRoot);
+        return foreign ? path.join(packageRoot, path.relative(foreign, part)) : part;
+      }).join(path.delimiter);
+      continue;
+    }
+    const foreign = path.isAbsolute(value) && checkoutFor(value, oldRoot, packageRoot);
+    if (!foreign) env[key] = value;
+    else if (corePathEnv.has(key)) env[key] = path.join(packageRoot, path.relative(foreign, value));
+    // Obsolete settings must not retain a path into another installation.
+  }
+  return env;
+}
+
+function publicPlist(plist) {
+  const copy = structuredClone(plist);
+  for (const key of Object.keys(copy.EnvironmentVariables || {})) {
+    if (/password|secret(?!s_brain)|token|api.?key|credential/i.test(key)) copy.EnvironmentVariables[key] = '[redacted]';
+  }
+  return copy;
+}
+
+function plistDiff(before, after) {
+  const lines = [];
+  const walk = (a, b, key) => {
+    if (JSON.stringify(a) === JSON.stringify(b)) return;
+    if (a && b && !Array.isArray(a) && !Array.isArray(b) && typeof a === 'object' && typeof b === 'object') {
+      for (const part of new Set([...Object.keys(a), ...Object.keys(b)])) walk(a[part], b[part], key ? `${key}.${part}` : part);
+    } else {
+      if (a !== undefined) lines.push(`- ${key}: ${JSON.stringify(a)}`);
+      if (b !== undefined) lines.push(`+ ${key}: ${JSON.stringify(b)}`);
+    }
+  };
+  walk(publicPlist(before), publicPlist(after), '');
+  return lines.join('\n') || 'No plist changes.';
+}
+
+export async function ensureServerService({ dryRun = false, platform = process.platform, home = os.homedir(),
+  packageRoot = PACKAGE_ROOT, env = process.env, exec = spawnSync, identity = processIdentity,
+  uid = process.getuid?.(), sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), attempts = 40 } = {}) {
+  if (platform !== 'darwin') return { status: 'unchanged', reason: 'server-release owns the server on systemd hosts; no changes made.' };
+  packageRoot = path.resolve(packageRoot);
+  const plistPath = path.join(home, 'Library/LaunchAgents', `${LABEL}.plist`);
+  const oldBytes = fs.existsSync(plistPath) ? fs.readFileSync(plistPath) : null;
+  const existing = oldBytes ? JSON.parse(convert(oldBytes, 'json', exec)) : {};
+  const template = fs.readFileSync(path.join(packageRoot, 'templates', `${LABEL}.plist`), 'utf8');
+  const desired = JSON.parse(convert(template, 'json', exec));
+  const substitute = value => typeof value === 'string' ? value.replaceAll('__ROOT__', packageRoot).replaceAll('__HOME__', home)
+    : Array.isArray(value) ? value.map(substitute) : value && typeof value === 'object'
+      ? Object.fromEntries(Object.entries(value).map(([key, val]) => [key, substitute(val)])) : value;
+  const plist = substitute(desired);
+  plist.WorkingDirectory = packageRoot;
+  plist.ProgramArguments[0] = stableNodePath(env);
+  plist.EnvironmentVariables = { ...plist.EnvironmentVariables,
+    ...serverEnvironment(existing.EnvironmentVariables, { packageRoot, oldRoot: existing.WorkingDirectory }) };
+  const diff = plistDiff(existing, plist);
+  if (dryRun) return { status: 'dry_run', plistPath, diff };
+
+  const xml = convert(JSON.stringify(plist), 'xml1', exec);
+  const domain = `gui/${uid}`;
+  const service = `${domain}/${LABEL}`;
+  const run = args => exec('launchctl', args, { encoding: 'utf8', timeout: 10000 });
+  const ok = result => result.status === 0 && !result.error;
+  const must = args => { if (!ok(run(args))) throw new Error(`launchctl ${args[0]} failed for ${service}.`); };
+  const agentDir = plist.EnvironmentVariables.AGENT_DIR || path.join(home, '.agent');
+  const pidFile = plist.EnvironmentVariables.TR_SERVER_PID_FILE || path.join(agentDir, 'skills/total-recall/server.pid');
+  const entry = path.join(packageRoot, 'src/server/index.mjs');
+  const previous = identity(pidFile, entry);
+  if (previous.status === 'unknown') throw new Error('Server process identity is unknown. Nothing changed.');
+  const loaded = ok(run(['print', service]));
+  if (!loaded && ['running', 'conflict'].includes(previous.status)) throw new Error('A server runs outside this LaunchAgent. Nothing changed.');
+  fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+  for (const log of [plist.StandardOutPath, plist.StandardErrorPath]) if (log) fs.mkdirSync(path.dirname(log), { recursive: true });
+  const pending = `${plistPath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(pending, xml, { mode: 0o600 });
+    fs.renameSync(pending, plistPath);
+    if (loaded) {
+      must(['bootout', service]);
+      let retired = false;
+      for (let i = 0; i < attempts; i++) {
+        if (!ok(run(['print', service]))) { retired = true; break; }
+        await sleep(250);
+      }
+      if (!retired) throw new Error('LaunchAgent did not retire.');
+    }
+    must(['bootstrap', domain, plistPath]);
+    for (let i = 0; i < attempts; i++) {
+      const observed = identity(pidFile, entry);
+      if (observed.status === 'running' && (!loaded || observed.pid !== previous.pid)) return { status: 'ready', plistPath, pid: observed.pid, entry: observed.entry };
+      await sleep(250);
+    }
+    throw new Error('Server process verification failed after launchd reload.');
+  } catch (error) {
+    // Keep the previous definition available for operator recovery. Never report success.
+    if (oldBytes !== null) fs.writeFileSync(plistPath, oldBytes, { mode: 0o600 });
+    else fs.rmSync(plistPath, { force: true });
+    throw error;
+  } finally { fs.rmSync(pending, { force: true }); }
+}

package/src/core/session-watcher.mjs

@@ -4,6 +4,7 @@ import os from 'os';
 import crypto from 'crypto';
 import { atomicWrite } from './vault.mjs';
 import { logger } from './logger.mjs';
+import { readLessonEntries } from './lesson-sessions.mjs';
 
 /**
  * Total Recall Session Watcher
@@ -30,6 +31,12 @@ const HOME = os.homedir();
  * of unified SSSS session entries.
  */
 const SOURCES = [
+  {
+    name: 'openclaw',
+    root: path.join(HOME, '.openclaw', 'agents'),
+    filter: filename => filename.endsWith('.jsonl'),
+    adapter: file => parseClaudeCode(file).map(entry => ({ ...entry, source: 'openclaw' })),
+  },
   {
     name: 'claude-code',
     root: path.join(HOME, '.claude', 'projects'),
@@ -248,6 +255,15 @@ export function parseClaudeCode(filePath) {
  */
 export function parseCodex(filePath) {
   const raw = fs.readFileSync(filePath, 'utf8');
+  if (/"type"\s*:\s*"(?:response_item|event_msg)"/.test(raw)) {
+    let parentId = null;
+    return readLessonEntries(filePath).map(message => {
+      const entry = createSessionEntry({ ...message, parentId, source: 'codex',
+        type: message.role === 'user' ? 'task' : message.role === 'tool' ? 'tool_call' : 'observation' });
+      parentId = entry.id;
+      return entry;
+    });
+  }
   const lines = raw.split('\n').filter(Boolean);
   const entries = [];
   let prevId = null;
@@ -661,7 +677,9 @@ export function writeSession(entries, sessionsDir, sourceFile) {
   // Skip if already ingested and unchanged
   if (fs.existsSync(sessionFile)) {
     try {
-      if (fs.readFileSync(sessionFile, 'utf8') === jsonl) {
+      const previous = fs.readFileSync(sessionFile, 'utf8');
+      const semantic = rows => JSON.stringify(rows.map(({ role, type, content, source, cwd }) => ({ role, type, content, source, cwd })));
+      if (previous === jsonl || semantic(previous.trim().split('\n').filter(Boolean).map(line => JSON.parse(line))) === semantic(entries)) {
         return null;
       }
     } catch { /* ignore */ }

package/src/core/skill-gap.mjs

@@ -0,0 +1,16 @@
+import { discoverPlugins } from './plugin-loader.mjs';
+import { runPluginCommand } from './plugin-runner.mjs';
+
+/** Skill engineering belongs to skill-manager. Missing operations fail closed. */
+export async function requestSkillGap(topic, evidence, { projectRoot = process.cwd(), discover = discoverPlugins, run = runPluginCommand } = {}) {
+  if (typeof topic !== 'string' || !topic.trim() || typeof evidence !== 'string' || !evidence.trim()) {
+    throw new Error('Skill gap requires a topic and an evidence reference');
+  }
+  const plugin = discover(projectRoot).find(item => item.id === 'skill-manager' && item.valid);
+  if (!plugin?.manifest.cli?.subcommands?.some(item => item.name === 'gap')) {
+    throw new Error('Skill-manager gap is unavailable. Install an owner version that provides: total-recall skill-manager gap "<topic>" --evidence <ref>');
+  }
+  const result = await run(plugin, { subcommand: 'gap', args: [topic.trim(), '--evidence', evidence], cwd: projectRoot });
+  if (!result.ok || result.truncated) throw new Error(`Skill-manager gap failed: ${result.stderr || result.output || result.exitCode}`);
+  return { success: true, output: result.stdout || result.output, executor: 'skill-manager' };
+}

package/src/core/ssss-kernel-bridge.mjs

@@ -12,7 +12,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import matter from './frontmatter.mjs';
-import { createEngine } from '@ssss/cli/engine';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createEngine, resolveContainedPath } from '@ssss/cli/engine';
 import { createValidator } from '@ssss/cli/validator';
 import {
   composeRegistryLayers,
@@ -20,6 +21,7 @@ import {
   resolvePrimitiveDefinition,
 } from '@ssss/cli/registry';
 import { detectDirectWrites } from '@ssss/cli/guard';
+import { checkRuleLength } from './rule-length.mjs';
 import { validateMemoryNode } from './total-recall-memory-validator.mjs';
 import {
   TOTAL_RECALL_HOST_EXTENSION,
@@ -66,6 +68,7 @@ const DIRECT_WRITE_APPROVED = [
 
 let cachedEngine = null;
 let cachedRegistryKey = '';
+const writePolicy = new AsyncLocalStorage();
 
 export function getKernelMode() {
   // Default to package-kernel cutover for core types (memory/workflow/low-risk).
@@ -187,7 +190,27 @@ export function getTotalRecallEngine(options = {}) {
   const registrySet = createTotalRecallRegistrySet(options);
   const key = `${[...registrySet.types.keys()].sort().join(',')}|${options.leaseStore || ''}`;
   if (!cachedEngine || cachedRegistryKey !== key || options.forceNew) {
-    const validator = createValidator({ registrySet });
+    const baseValidator = createValidator({ registrySet });
+    const validator = {
+      ...baseValidator,
+      validateData(data, callOptions) {
+        const result = baseValidator.validateData(data, callOptions);
+        const context = writePolicy.getStore();
+        if (context?.envelope.type !== 'patch') return result;
+        // The kernel calls validateData with the merged frontmatter. Check the
+        // replacement body against that category and those exception tags.
+        // A metadata-only patch keeps the current document body.
+        const { envelope, vaultRoot, options } = context;
+        const body = envelope.patches.__body__ === undefined
+          ? matter(fs.readFileSync(resolveContainedPath(vaultRoot, envelope.path), 'utf8')).content
+          : String(envelope.patches.__body__);
+        const policy = checkRuleLength(data, body, options);
+        context.warnings.push(...policy.warnings);
+        return { ...result, valid: result.valid && !policy.errors.length,
+          errors: [...result.errors, ...policy.errors],
+          field_errors: [...result.field_errors, ...policy.errors.map(issue => ({ field: '__body__', issue }))] };
+      },
+    };
     cachedEngine = createEngine({
       registrySet,
       validator,
@@ -277,6 +300,9 @@ export function prepareEnvelopeForKernel(envelope, options = {}) {
       return { envelope: env, warnings, errors: [`Content parsing error: ${error.message}`] };
     }
     const data = { ...parsed.data };
+    const length = checkRuleLength(data, parsed.content, options);
+    errors.push(...length.errors);
+    warnings.push(...length.warnings);
 
     // Package 0.9 universal frontmatter.
     if (!data.title && data.name) data.title = data.name;
@@ -392,11 +418,13 @@ export async function processViaPackageKernel(envelope, vaultRoot, options = {})
 
   const eventsDir = path.join(vaultRoot, '.events');
   if (!env.dry_run && !fs.existsSync(eventsDir)) fs.mkdirSync(eventsDir, { recursive: true });
-  const response = await engine.processOperation(env, vaultRoot, {
+  const context = { envelope: env, vaultRoot, options, warnings: [] };
+  const response = await writePolicy.run(context, () => engine.processOperation(env, vaultRoot, {
     ...options,
     vaultRoot,
     principal: options.principal || mapTrPrincipal(env, options, vaultRoot),
-  });
+  }));
+  prepared.warnings.push(...context.warnings);
 
   if (prepared.warnings.length && response?.validation) {
     response.validation.warnings = [

package/src/core/startup-health.mjs

@@ -148,7 +148,12 @@ export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl =
       remoteDaemon = { status: body.daemon === 'running' ? 'running' : ['dead', 'stopped', 'not-started'].includes(body.daemon) ? 'stopped' : 'unknown', source: 'remote-health' };
       if (local) {
         const own = identity(serverFile, path.join(packageRoot, 'src', 'server', 'index.mjs'));
-        if (own.status !== 'running') return { status: own.status === 'conflict' ? 'conflict' : 'unknown', reason: 'server-process-unverified' };
+        if (own.status !== 'running') {
+          const actualRoot = own.entry?.endsWith(path.join('src', 'server', 'index.mjs'))
+            ? path.resolve(path.dirname(own.entry), '../..') : null;
+          return { status: own.status === 'conflict' ? 'conflict' : 'unknown',
+            reason: actualRoot ? `server runs from ${actualRoot}; expected ${packageRoot}; run total-recall server ensure` : 'server-process-unverified' };
+        }
         if (!await listener(own.pid, new URL(brainUrl), { run, cwd })) return { status: 'unknown', reason: 'server-listener-unverified' };
       }
       const drift = local && verdict.status === 'ready' ? serverCodeDrift(verdict.version, onDiskVersion()) : null;

package/src/core/surface.mjs

@@ -496,13 +496,8 @@ function injectDirectives(fileContent, rulesBlock) {
     return prependDirectives(authored, rulesBlock);
   }
   
-  let content = fileContent.trimEnd();
-  const baseline = '# 🔴 MANDATORY FIRST STEP ON EVERY TURN: TOTAL RECALL FIRST\n1. Run `total-recall --help` (or `node bin/total-recall.mjs --help`) to discover all tools, plugins, and commands.\n2. Read and follow .agent/skills/total-recall/SKILL.md before doing ANYTHING.\n3. Run `total-recall context "<task>"` and `total-recall recall "<topic>" --local` before any decision or action.\nTotal Recall is the mandatory working memory and toolset across all tasks and harnesses. Never skip this.';
-  if (!content.includes('total-recall/SKILL.md')) {
-    content = baseline + '\n\n' + content;
-  }
-  
-  return prependDirectives(content, rulesBlock);
+  // The managed block carries the start-here instructions; authored text stays as written.
+  return prependDirectives(fileContent.trimEnd(), rulesBlock);
 }
 
 function prependDirectives(authored, rulesBlock) {
@@ -516,14 +511,28 @@ function prependDirectives(authored, rulesBlock) {
 /**
  * Write or update a platform instruction shim with the pointer and active rules.
  */
+/**
+ * The whole managed part of every client entry file (ON-DEMAND-CONTEXT-01). It is static: no rule
+ * bodies, CLI list, plugin table or command list, so a rule or plugin change rewrites no repository.
+ * The rules for a task are compiled when the agent acknowledges preflight, and commands are looked
+ * up when needed.
+ */
+export const ENTRY_BLOCK = `# Total Recall: start here
+
+This repository uses Total Recall. Its rules are not copied into this file: they are compiled for your task when you acknowledge preflight.
+
+1. Read \`.agent/skills/total-recall/SKILL.md\`.
+2. Run \`total-recall tr-preflight --ack --task "<task>" --action read,edit,test\` and read everything it prints. Those are the rules for this task. Until it passes, working tools are denied.
+3. Route the task through Metaharness with \`total-recall meta-harness route "<task>" --json\` and follow the route.
+4. Look commands up only when you need them: \`total-recall --help\`, \`total-recall <namespace> --help\`, \`total-recall plugin library\`.`;
+
 async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir, force = false } = {}) {
   const shimDir = path.dirname(shimPath);
-  const rulesBlock = await buildRulesBlock(skillsDir, nodes, { vaultDir, derivedDir, bootstrap: true });
-  const baseline = '# 🔴 MANDATORY FIRST STEP ON EVERY TURN: TOTAL RECALL FIRST\n1. Run `total-recall --help` (or `node bin/total-recall.mjs --help`) to discover all tools, plugins, and commands.\n2. Read and follow .agent/skills/total-recall/SKILL.md before doing ANYTHING.\n3. Run `total-recall context "<task>"` and `total-recall recall "<topic>" --local` before any decision or action.\nTotal Recall is the mandatory working memory and toolset across all tasks and harnesses. Never skip this.\n';
+  const rulesBlock = ENTRY_BLOCK;
   const mdcHeader = shimPath.endsWith('.mdc')
-    ? '---\ndescription: "Total Recall — Auto-generated behavioral memory surface."\nglobs:\nalwaysApply: true\n---\n\n'
+    ? '---\ndescription: "Total Recall — start here."\nglobs:\nalwaysApply: true\n---\n\n'
     : '';
-  const fullContent = prependDirectives(`${mdcHeader}${baseline}`, rulesBlock);
+  const fullContent = prependDirectives(mdcHeader, rulesBlock);
 
   try {
     const normShim = path.normalize(shimPath);
@@ -772,46 +781,50 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
     ? mergeGlobalRuleNodes(nodes, getNodes(globalVault))
     : nodes;
 
-  // ── Incremental compilation: vault content hash check ──
-  // The global rules hash lives in its own file: vault-hash.txt is served by
-  // /api/vault/hash and must keep describing this vault alone.
+  // ── Each output has its own trigger (ON-DEMAND-CONTEXT-01) ──
+  // Entry files are static: they change only with the entry block or the client list.
+  // Indexes change only with this vault. The CLI index changes only with this brain's
+  // plugin catalog. A plugin or global-rule change therefore rewrites no repository's
+  // entry files and starts no embeddings pass; rules reach agents at preflight.
   const hashFile = path.join(derivedDir, 'vault-hash.txt');
   const currentHash = computeVaultHash(vaultDir);
-  const globalHashFile = path.join(derivedDir, 'global-rules-hash.txt');
-  const globalHash = globalVault && fs.existsSync(globalVault) ? computeVaultHash(globalVault) : '';
-  // Commands and skills feed the surface too; a change to either must recompile
-  // even when no memory node changed.
   const inputsHashFile = path.join(derivedDir, 'surface-inputs-hash.txt');
+  const cliHashFile = path.join(derivedDir, 'cli-index-hash.txt');
   const files = instructionFiles(instructionsFile, skillsDir);
   const surfaceDir = path.dirname(instructionsFile);
   const artifactsFile = path.join(derivedDir, 'surface-artifacts.json');
-  const inputsHash = sourceHash(SURFACE_SOURCE) + catalog.fingerprint + JSON.stringify(files) + surfaceInputsHash({ commandDirs: commandDirsFor(skillsDir), skillsDir });
-
-  if (!force && fs.existsSync(hashFile)) {
-    const storedHash = fs.readFileSync(hashFile, 'utf8').trim();
-    const storedGlobal = fs.existsSync(globalHashFile) ? fs.readFileSync(globalHashFile, 'utf8').trim() : '';
-    const storedInputs = fs.existsSync(inputsHashFile) ? fs.readFileSync(inputsHashFile, 'utf8').trim() : '';
-    if (storedHash === currentHash && storedGlobal === globalHash && storedInputs === inputsHash &&
-        instructionArtifactsMatch(files, surfaceDir, artifactsFile)) {
-      return {
-        nodesProcessed: nodes.length,
-        skillsInjected: 0,
-        semanticIndexed: 0,
-        semanticUnavailable: false,
-        skipped: true,
-        reason: 'vault-hash-unchanged'
-      };
-    }
+  const inputsHash = crypto.createHash('sha256').update(ENTRY_BLOCK).update(JSON.stringify(files.map(file => path.relative(surfaceDir, file)))).digest('hex');
+  const stored = file => (fs.existsSync(file) ? fs.readFileSync(file, 'utf8').trim() : null);
+  const entryCurrent = !force && stored(inputsHashFile) === inputsHash && instructionArtifactsMatch(files, surfaceDir, artifactsFile);
+  const vaultCurrent = !force && stored(hashFile) === currentHash;
+  const cliCurrent = !force && stored(cliHashFile) === catalog.fingerprint;
+
+  if (entryCurrent && vaultCurrent && cliCurrent) {
+    return {
+      nodesProcessed: nodes.length,
+      skillsInjected: 0,
+      semanticIndexed: 0,
+      semanticUnavailable: false,
+      skipped: true,
+      reason: 'vault-hash-unchanged'
+    };
   }
 
-  // 1. Write pointer and active rules to all instruction shims
-  const skillsInjected = await compilePointers(instructionsFile, skillsDir, ruleNodes, { vaultDir, derivedDir, force, files });
-
-  // 2. Build derived indexes (powers semantic search API)
   if (!fs.existsSync(derivedDir)) {
     fs.mkdirSync(derivedDir, { recursive: true });
   }
 
+  // 1. Entry files, only when the entry block or client list changed (or a file drifted).
+  const skillsInjected = entryCurrent ? 0 : await compilePointers(instructionsFile, skillsDir, ruleNodes, { vaultDir, derivedDir, force, files });
+  if (!entryCurrent) {
+    atomicWrite(inputsHashFile, inputsHash);
+    atomicWrite(artifactsFile, JSON.stringify({ version: 1, files: files.map(file => describeInstruction(file, surfaceDir)) }, null, 2));
+  }
+
+  // 2. Derived indexes, only when this vault changed.
+  let semanticResult = { indexed: 0, skipped: nodes.length, unavailable: false };
+  if (!vaultCurrent) {
+
   const graphIndex = nodes.map(n => ({
     slug: n.slug,
     title: n.title,
@@ -844,7 +857,7 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
   //     caller could detect any of it.
   // Awaiting is cheap in steady state: buildEmbeddingsIndex skips nodes whose
   // content hash is unchanged, so only genuinely new or edited nodes cost a call.
-  let semanticResult = { indexed: 0, skipped: nodes.length, unavailable: true };
+  semanticResult = { indexed: 0, skipped: nodes.length, unavailable: true };
   if (!semantic || process.env.TR_EMBEDDINGS_DISABLED === '1') {
     logger.info('surface', 'Semantic embeddings explicitly disabled; local indexes updated.', { derivedDir });
   } else try {
@@ -869,9 +882,18 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
     semanticResult = { indexed: 0, skipped: nodes.length, unavailable: true, error: err.message };
   }
 
-  // 3b. Build or update the CLI semantic index.
-  let cliIndexResult = { built: 0, skipped: 0, failed: 0 };
+  // 4. Generate Obsidian Canvas
   try {
+    generateCanvas(nodes, vaultDir);
+  } catch { /* non-fatal */ }
+
+  atomicWrite(hashFile, currentHash);
+  writeProjectionManifest(derivedDir, currentHash);
+  }
+
+  // 3. The CLI semantic index, only when this brain's plugin catalog changed.
+  let cliIndexResult = { built: 0, skipped: 0, failed: 0 };
+  if (!cliCurrent) try {
     const { buildCliSemanticIndex } = await import('./cli-semantic-index.mjs');
     const projectRoot = skillsDir ? path.dirname(path.dirname(skillsDir)) : process.cwd();
     cliIndexResult = await buildCliSemanticIndex({
@@ -884,22 +906,11 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
     if (cliIndexResult.built > 0) {
       logger.info('surface', `CLI semantic index: ${cliIndexResult.built} indexed, ${cliIndexResult.skipped} skipped.`, { derivedDir });
     }
+    atomicWrite(cliHashFile, catalog.fingerprint);
   } catch (err) {
     logger.warn('surface', `CLI semantic index build non-fatal warning: ${err.message}`, { derivedDir });
   }
 
-  // 4. Generate Obsidian Canvas
-  try {
-    generateCanvas(nodes, vaultDir);
-  } catch { /* non-fatal */ }
-
-  // 5. Write vault hash + projection manifest
-  atomicWrite(hashFile, currentHash);
-  atomicWrite(globalHashFile, globalHash);
-  atomicWrite(inputsHashFile, inputsHash);
-  atomicWrite(artifactsFile, JSON.stringify({ version: 1, files: files.map(file => describeInstruction(file, surfaceDir)) }, null, 2));
-  writeProjectionManifest(derivedDir, currentHash);
-
   return {
     nodesProcessed: nodes.length,
     skillsInjected,