total-recall-brain 3.40.7 → 3.41.0

package/src/core/required-plugins.mjs

@@ -1,12 +1,43 @@
-/** Required native capability installation checks; never opens credential state. */
+/**
+ * Required native capability installation checks; never opens credential state.
+ *
+ * The nine defaults live in ONE shared folder per machine — the global brain.
+ * A project brain never receives its own copy: discovery already falls back to
+ * the shared folder, and a repository switches a shared plugin on or off with
+ * its own `plugin_record` overlay. Copies made by earlier releases are reported
+ * by `plugin copies` so they can be audited and removed.
+ */
 import fs from 'node:fs';
 import path from 'node:path';
-import { readPluginsDir, PACKAGE_ROOT, resolvePluginFile } from './plugin-loader.mjs';
+import { readPluginsDir, globalPluginsDir, PACKAGE_ROOT, resolvePluginFile } from './plugin-loader.mjs';
 import { DEFAULT_PLUGIN_IDS } from './default-plugins.mjs';
+import { comparePackageVersions } from './package-version.mjs';
 import { preparePluginDependencies } from './plugin-dependencies.mjs';
 
-export function inspectRequiredPlugins(brainDir) {
-  const plugins = readPluginsDir(path.join(brainDir, 'plugins'), 'required');
+/**
+ * True when this brain is the shared (global) brain that owns the defaults.
+ */
+function isSharedBrain(brainDir) {
+  return path.resolve(brainDir) === path.resolve(path.dirname(globalPluginsDir()));
+}
+
+/**
+ * Validate the required capability for a brain. A shared brain validates its own
+ * installs; a project brain validates its own copy when it still has one and
+ * otherwise the shared folder that discovery already falls back to.
+ */
+export function inspectRequiredPlugins(brainDir, { pluginsDir, sharedBrainDir } = {}) {
+  const ownDir = path.join(brainDir, 'plugins');
+  const sharedPlugins = sharedBrainDir ? path.join(sharedBrainDir, 'plugins') : globalPluginsDir();
+  // A project brain's plugins directory can exist yet hold none of the defaults
+  // (provisioning creates it empty). The shared folder is what actually serves
+  // the repository, so consult it whenever this brain carries no auth of its own.
+  const resolved = pluginsDir || (isSharedBrain(brainDir) ? globalPluginsDir()
+    : (hasOwnRequired(ownDir) ? ownDir : sharedPlugins));
+  const own = readPluginsDir(ownDir, 'required');
+  const shared = path.resolve(resolved) === path.resolve(ownDir) ? [] : readPluginsDir(resolved, 'shared');
+  const seen = new Set();
+  const plugins = [...own, ...shared].filter(plugin => (seen.has(plugin.id) ? false : seen.add(plugin.id)));
   const errors = [];
   const auth = plugins.find(plugin => plugin.id === 'auth');
   if (!auth?.valid) errors.push('Required auth plugin is missing or invalid');
@@ -23,24 +54,131 @@ export function inspectRequiredPlugins(brainDir) {
       } catch { errors.push(`Required auth file is missing or unsafe: ${file || 'CLI handler'}`); }
     }
   }
-  return { status: errors.length ? 'failed' : 'ready', errors };
+  const source = !auth ? null : (path.resolve(auth.pluginsDir) === path.resolve(ownDir) ? 'local' : 'shared');
+  return { status: errors.length ? 'failed' : 'ready', errors, source };
+}
+
+/** True when this brain carries the required plugin itself rather than by fallback. */
+function hasOwnRequired(ownDir) {
+  return fs.existsSync(path.join(ownDir, 'auth', 'plugin.json'));
+}
+
+/** Only a copy that declares an older release than the bundled one is refreshed; damaged same-release copies still fail. */
+function isStaleInstall(target, source) {
+  try {
+    const installed = JSON.parse(fs.readFileSync(path.join(target, 'plugin.json'), 'utf8')).version;
+    const bundled = JSON.parse(fs.readFileSync(path.join(source, 'plugin.json'), 'utf8')).version;
+    return comparePackageVersions(installed, bundled) === -1;
+  } catch { return false; }
 }
 
-export function ensureRequiredPlugins(brainDir, { sourceDir = path.join(PACKAGE_ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins') } = {}) {
+/**
+ * Ensure the required plugins exist for a brain.
+ *
+ * There is one shared install per machine, in the global brain. A project brain
+ * never receives a copy: it is served by the shared folder, and a repository
+ * switches a shared plugin on or off with its own record. Provisioning a project
+ * therefore makes sure the SHARED brain is seeded, then validates that the
+ * required capability resolves for the project. Copies left in a project by an
+ * earlier release are refreshed in place (so they stay usable until removed),
+ * never created.
+ */
+export function ensureRequiredPlugins(brainDir, { sourceDir = path.join(PACKAGE_ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins'), sharedBrainDir } = {}) {
   // Validate the complete package before changing any installation.
   for (const id of DEFAULT_PLUGIN_IDS) {
     if (!fs.existsSync(path.join(sourceDir, id, 'plugin.json'))) throw new Error(`Required bundled ${id} plugin is missing`);
   }
+  if (!isSharedBrain(brainDir)) {
+    // A repository installs nothing of its own. The shared brain is what serves
+    // it, so seed that one — never this project's plugins directory.
+    const sharedBrain = sharedBrainDir || path.dirname(globalPluginsDir());
+    if (path.resolve(sharedBrain) !== path.resolve(brainDir)) installDefaultsInto(sharedBrain, sourceDir);
+    return inspectRequired(brainDir, { sharedBrainDir: sharedBrain });
+  }
+  installDefaultsInto(brainDir, sourceDir);
+  return inspectRequired(brainDir);
+}
+
+/** Seed or refresh the default plugins inside one brain. */
+function installDefaultsInto(brainDir, sourceDir) {
   for (const id of DEFAULT_PLUGIN_IDS) {
-  const target = path.join(brainDir, 'plugins', id);
-  if (!fs.existsSync(target)) {
+    const target = path.join(brainDir, 'plugins', id);
     const source = path.join(sourceDir, id);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.cpSync(source, target, { recursive: true, force: false, errorOnExist: true });
-  }
-  preparePluginDependencies(target);
+    if (!fs.existsSync(target)) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.cpSync(source, target, { recursive: true, force: false, errorOnExist: true });
+    } else if (isStaleInstall(target, source)) {
+      // A vendored copy that no longer validates (or predates the bundled release) is replaced; node_modules stays.
+      for (const entry of fs.readdirSync(target)) if (entry !== 'node_modules') fs.rmSync(path.join(target, entry), { recursive: true, force: true });
+      for (const entry of fs.readdirSync(source)) if (entry !== 'node_modules') fs.cpSync(path.join(source, entry), path.join(target, entry), { recursive: true });
+    }
+    preparePluginDependencies(target);
   }
-  const report = inspectRequiredPlugins(brainDir);
+}
+
+/** Validate and fail loudly; provisioning must not report a brain it cannot serve. */
+function inspectRequired(brainDir, options = {}) {
+  const report = inspectRequiredPlugins(brainDir, options);
   if (report.status !== 'ready') throw new Error(report.errors.join('; '));
   return report;
 }
+
+/**
+ * Audit per-repository copies of the shared defaults.
+ *
+ * A copy is compared with the bundled plugin source this package ships, because
+ * that is what an install was made from. The comparison ignores installed
+ * dependencies, test scaffolding and a shared install's own generated state, so
+ * a copy reports `edited` only when its plugin source differs — meaning somebody
+ * changed the plugin inside that repository, and it must not be removed blindly.
+ */
+export function auditProjectPluginCopies(projectRoot, { sharedDir = globalPluginsDir(), sourceDir = path.join(PACKAGE_ROOT, 'scaffold', '.agent', 'skills', 'total-recall', 'plugins') } = {}) {
+  const pluginsDir = path.join(projectRoot, '.agent', 'skills', 'total-recall', 'plugins');
+  if (!fs.existsSync(pluginsDir)) return { copies: [], count: 0, sourceDir };
+  const copies = [];
+  for (const id of DEFAULT_PLUGIN_IDS) {
+    const copyDir = path.join(pluginsDir, id);
+    if (!fs.existsSync(copyDir)) continue;
+    const source = path.join(sourceDir, id);
+    const shared = path.join(sharedDir, id);
+    const row = {
+      id, dir: copyDir,
+      sourceDir: fs.existsSync(source) ? source : null,
+      sharedDir: fs.existsSync(shared) ? shared : null,
+      edited: null, version: null, sourceVersion: null, sharedVersion: null
+    };
+    const version = (dir) => { try { return JSON.parse(fs.readFileSync(path.join(dir, 'plugin.json'), 'utf8')).version; } catch { return null; } };
+    row.version = version(copyDir);
+    row.sourceVersion = row.sourceDir ? version(row.sourceDir) : null;
+    row.sharedVersion = row.sharedDir ? version(row.sharedDir) : null;
+    row.edited = row.sourceDir ? !sameTree(copyDir, row.sourceDir) : null;
+    copies.push(row);
+  }
+  return { copies, count: copies.length, sourceDir };
+}
+
+/** Compare two plugin trees, ignoring installed dependencies and generated state. */
+function sameTree(left, right) {
+  const ignore = new Set(['node_modules', '.git', 'test', 'vitest.config.mjs', 'package-lock.json']);
+  // A shared install runs in place, so its tree also carries compiled surfaces
+  // and a local secrets projection. Those are not plugin source.
+  const ignored = (name) => ignore.has(name) || name.startsWith('.env');
+  const walk = (dir, base = '') => {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (ignored(entry.name)) continue;
+      const relative = base ? `${base}/${entry.name}` : entry.name;
+      const full = path.join(dir, entry.name);
+      // Symlinks are compared by their target text; a linked dev checkout is not
+      // "edited", it is owned elsewhere.
+      if (entry.isSymbolicLink()) { out.push([relative, `link:${fs.readlinkSync(full)}`]); continue; }
+      if (entry.isDirectory()) { out.push(...walk(full, relative)); continue; }
+      out.push([relative, fs.readFileSync(full, 'utf8')]);
+    }
+    return out;
+  };
+  try {
+    const a = walk(left); const b = walk(right);
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch { return false; }
+}

package/src/core/skills-registry.mjs

@@ -93,7 +93,7 @@ export function skillPackageFiles(skillDir) {
   const files = [];
   const visit = (dir, relative = '') => {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === '.DS_Store') continue;
+      if (skillPackageExcluded(entry.name)) continue;
       const next = relative ? `${relative}/${entry.name}` : entry.name;
       if (entry.isDirectory()) visit(path.join(dir, entry.name), next);
       else if (entry.isFile() || entry.isSymbolicLink()) files.push(next);
@@ -264,14 +264,38 @@ export function listInstalls(brainDir, { skillId = null, repo = null } = {}) {
 }
 
 /**
- * Recursive copy of skill directory (skip node_modules, .git).
+ * State that is never part of a skill package.
+ *
+ * A skill's package is its content: SKILL.md, references, prompts, scripts,
+ * subagents, evals and assets. Everything listed here is either the agent's
+ * private state, disposable derived data, or a nested install belonging to
+ * something else — and `config/secrets.enc` is the credential store itself,
+ * which must never be copied into another repository or published. Excluding
+ * them also stops the package hash changing every time memory is written.
+ */
+const SKILL_PACKAGE_EXCLUDED_DIRS = new Set([
+  'node_modules', '.git', 'memory-vault', 'memory-derived', 'derived',
+  'sessions', 'logs', 'browser-profile', 'plugins', 'plugin-state',
+  'memory-inbox', 'dist', 'coverage', '.cache', 'tmp',
+]);
+const SKILL_PACKAGE_EXCLUDED_FILES = [
+  /^\.DS_Store$/, /^secrets\.enc(\.|$)/, /^\.env(\.|$)/, /^id_[a-z]+$/, /\.pem$/,
+];
+
+/** True when a directory entry is private, derived or a nested install. */
+export function skillPackageExcluded(name) {
+  return SKILL_PACKAGE_EXCLUDED_DIRS.has(name) || SKILL_PACKAGE_EXCLUDED_FILES.some((re) => re.test(name));
+}
+
+/**
+ * Recursive copy of skill directory, content only.
  */
 export function copySkillDir(src, dest) {
   if (!fs.existsSync(src)) throw new Error(`Source missing: ${src}`);
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
   for (const ent of entries) {
-    if (ent.name === 'node_modules' || ent.name === '.git' || ent.name === '.DS_Store') continue;
+    if (skillPackageExcluded(ent.name)) continue;
     const from = path.join(src, ent.name);
     const to = path.join(dest, ent.name);
     if (ent.isDirectory()) {

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

@@ -20,7 +20,6 @@ import {
   resolvePrimitiveDefinition,
 } from '@ssss/cli/registry';
 import { detectDirectWrites } from '@ssss/cli/guard';
-import { logger } from './logger.mjs';
 import { validateMemoryNode } from './total-recall-memory-validator.mjs';
 import {
   TOTAL_RECALL_HOST_EXTENSION,
@@ -56,6 +55,7 @@ const DIRECT_WRITE_APPROVED = [
   'src/core/ssss-kernel-bridge.mjs',
   'src/core/validated-write.mjs',
   'src/core/vault.mjs',
+  'src/core/vault-files.mjs',
   'src/core/surface.mjs',
   'src/core/blackboard.mjs',
   'src/core/steering.mjs',
@@ -450,6 +450,8 @@ export function compareVerdicts(localResult, kernelResult) {
 }
 
 export async function shadowCompare(envelope, vaultRoot, localResult, options = {}) {
+  // Ordinary kernel mutations must not bootstrap configuration/auth/plugins.
+  const { logger } = await import('./logger.mjs');
   const dryEnvelope = { ...envelope, dry_run: true };
   try {
     const kernelResult = await processViaPackageKernel(dryEnvelope, vaultRoot, options);

package/src/core/startup-health.mjs

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readProcessCommand } from './pid-lock.mjs';
 import { CLI_COMMANDS } from './cli-commands.mjs';
@@ -12,8 +12,8 @@ export const cliEntry = path.join(packageRoot, 'bin/total-recall.mjs');
 
 export function runBounded(binary, args, { cwd = process.cwd(), timeoutMs = 15000, maxBytes = 262144 } = {}) {
   return new Promise(resolve => {
-    let child, output = '', size = 0, reason = null, settled = false, timer, escalation;
-    const finish = code => { if (settled) return; settled = true; clearTimeout(timer); resolve({ code, output, reason }); };
+    let child, output = '', stderr = '', size = 0, reason = null, settled = false, timer, escalation;
+    const finish = code => { if (settled) return; settled = true; clearTimeout(timer); resolve({ code, output, stderr: stderr.slice(-2000), reason }); };
     const kill = signal => { try { if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal); else child.kill(signal); } catch {} };
     const stop = why => { if (reason || settled) return; reason = why; kill('SIGTERM'); escalation = setTimeout(() => { kill('SIGKILL'); finish(null); }, 500); };
     try { child = spawn(binary, args, { cwd, shell: false, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] }); }
@@ -21,7 +21,7 @@ export function runBounded(binary, args, { cwd = process.cwd(), timeoutMs = 1500
     timer = setTimeout(() => stop('timeout'), timeoutMs);
     child.on('error', () => { reason = 'spawn-failed'; clearTimeout(escalation); finish(null); });
     child.stdout.on('data', chunk => { size += chunk.length; if (size <= maxBytes) output += chunk.toString(); else stop('output-limit'); });
-    child.stderr.on('data', chunk => { size += chunk.length; if (size > maxBytes) stop('output-limit'); });
+    child.stderr.on('data', chunk => { size += chunk.length; if (size <= maxBytes) stderr += chunk.toString(); else stop('output-limit'); });
     child.on('close', code => { if (!reason) finish(code); });
   });
 }
@@ -33,16 +33,57 @@ export async function verifyListener(pid, url, { run = runBounded, cwd = process
   return result.code === 0 && !result.reason && result.output.split(/\r?\n/).includes(`p${pid}`);
 }
 
-export function processIdentity(pidFile, hint, { alive = pid => { try { process.kill(pid, 0); return true; } catch { return false; } }, command = readProcessCommand } = {}) {
+/** A process's working directory, or null when it cannot be determined. */
+export function readProcessCwd(pid, { run = spawnSync } = {}) {
+  try {
+    const res = run('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { encoding: 'utf8', timeout: 5_000 });
+    if (res.status !== 0 || !res.stdout) return null;
+    const line = res.stdout.split(/\r?\n/).find(l => l.startsWith('n'));
+    return line ? line.slice(1) || null : null;
+  } catch { return null; }
+}
+
+/**
+ * Does the process holding `pid` look like the entry at `hint`?
+ *
+ * A launch agent starts its program with a path relative to the service's
+ * WorkingDirectory (`node src/server/index.mjs`), so the recorded command line
+ * carries no absolute path. Resolving it against the *caller's* cwd made this
+ * check depend on where the operator happened to stand: `total-recall startup
+ * check` run from any other directory reported a healthy local server as
+ * `server-process-unverified`. Resolve against the process's own cwd instead,
+ * An unresolved entry is unknown; a matching suffix alone cannot identify an
+ * installation and must never authorize lifecycle actions.
+ */
+export function processIdentity(pidFile, hint, { alive = pid => { try { process.kill(pid, 0); return true; } catch (err) { if (err.code === 'ESRCH') return false; throw err; } }, command = readProcessCommand, cwd = readProcessCwd } = {}) {
   let pid;
-  try { pid = Number(fs.readFileSync(pidFile, 'utf8').trim()); } catch { return { status: 'not-started' }; }
-  if (!Number.isInteger(pid) || pid <= 0 || !alive(pid)) return { status: 'stopped' };
-  const cmd = command(pid);
-  if (!cmd) return { status: 'unknown', reason: 'process-identity-unavailable' };
+  try { pid = Number(fs.readFileSync(pidFile, 'utf8').trim()); }
+  catch (err) { return err.code === 'ENOENT' ? { status: 'not-started' } : { status: 'unknown', reason: 'pid-unreadable' }; }
+  if (!Number.isInteger(pid) || pid <= 0) return { status: 'unknown', reason: 'invalid-pid' };
+  try { if (!alive(pid)) return { status: 'stopped' }; }
+  catch { return { status: 'unknown', reason: 'process-liveness-unavailable', pid }; }
+  let cmd;
+  try { cmd = command(pid); } catch { /* unknown below */ }
+  if (!cmd) return { status: 'unknown', reason: 'process-identity-unavailable', pid };
   const script = cmd.trim().match(/^(?:\S*node(?:\s+--[^ ]+)*)\s+(\S+)/)?.[1];
-  let matches = false;
-  try { matches = Boolean(script) && fs.realpathSync(script) === fs.realpathSync(hint); } catch {}
-  return matches ? { status: 'running', pid } : { status: 'conflict', reason: 'foreign-pid' };
+  let entry = null;
+  if (script) {
+    // Absolute script paths resolve directly; relative ones resolve against the
+    // process's own working directory, never the caller's.
+    try {
+      const base = path.isAbsolute(script) ? null : cwd(pid);
+      if (!path.isAbsolute(script) && !base) throw new Error('Missing process cwd');
+      entry = fs.realpathSync(base ? path.resolve(base, script) : script);
+      if (entry === fs.realpathSync(hint)) return { status: 'running', pid, entry };
+    } catch { return { status: 'unknown', reason: 'process-entry-unavailable', pid }; }
+  }
+  return { status: 'conflict', reason: 'foreign-pid', pid, ...(entry ? { entry } : {}) };
+}
+
+/** The single installation-aware daemon observation for status and lifecycle. */
+export function observeDaemon(brainDir, { identity = processIdentity } = {}) {
+  const expected_entry = path.join(packageRoot, 'src', 'core', 'daemon-loop.mjs');
+  return { ...identity(path.join(brainDir, 'daemon.pid'), expected_entry), expected_entry, source: 'local-pid' };
 }
 
 export function healthVerdict(body) {
@@ -81,7 +122,6 @@ export async function fetchStartup(url, options = {}, fetchImpl = fetch) {
 export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl = null, token = null, brainId = null, ensure = false,
   appCheck = null, appStart = null, run = runBounded, fetchImpl = fetch, listener = verifyListener, platform = process.platform, home = os.homedir(), identity = processIdentity } = {}) {
   const actions = [];
-  const daemonFile = path.join(brainDir, 'daemon.pid');
   const serverFile = path.join(brainDir, 'server.pid');
   const report = { checked_at: new Date().toISOString(), server: { status: 'not-configured' }, brain: { status: 'unknown' }, daemon: { status: 'unknown' },
     ssss: { status: 'unknown', role: 'document-engine-tooling; no standalone daemon required' }, app: { status: 'not-declared' }, actions };
@@ -105,7 +145,7 @@ export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl =
     } catch { return { status: 'offline', reason: 'health-unreachable' }; }
   };
   report.server = await probeServer();
-  report.daemon = local ? { ...identity(daemonFile, path.join(packageRoot, 'src', 'core', 'daemon-loop.mjs')), source: 'local-pid' } : remoteDaemon;
+  report.daemon = local ? observeDaemon(brainDir, { identity }) : remoteDaemon;
   const serverIdentity = local ? identity(serverFile, path.join(packageRoot, 'src', 'server', 'index.mjs')) : null;
   if (ensure && local && report.server.status === 'offline' && ['not-started', 'stopped'].includes(serverIdentity.status)) {
     const plist = path.join(home, 'Library', 'LaunchAgents', 'com.totalrecall.server.plist');
@@ -126,7 +166,7 @@ export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl =
       const result = await run(process.execPath, [cliEntry, 'daemon', 'start'], { cwd });
       actions.push({ component: 'daemon', action: 'cli-start', accepted: result.code === 0 && !result.reason });
       for (let i = 0; i < 10; i++) {
-        report.daemon = { ...identity(daemonFile, path.join(packageRoot, 'src', 'core', 'daemon-loop.mjs')), source: 'local-pid' }; if (report.daemon.status === 'running') break;
+        report.daemon = observeDaemon(brainDir, { identity }); if (report.daemon.status === 'running') break;
         await new Promise(resolve => setTimeout(resolve, 200));
       }
     }
@@ -146,7 +186,17 @@ export async function startupHealth({ cwd = process.cwd(), brainDir, brainUrl =
       }
     } catch { report.brain = { status: 'offline', reason: 'instructions-unreachable' }; }
   }
-  const candidates = [path.join(cwd, 'ssss'), path.join(cwd, 'node_modules', '.bin', 'ssss')];
+  // SSSS is tooling that may be vendored by the project under test, installed
+  // alongside this package, or only on PATH. Searching `cwd` alone reported a
+  // working install as `unavailable` whenever the operator ran the check from
+  // anywhere other than a repository root, which made `shared_ready` depend on
+  // the caller's directory rather than on the machine.
+  const candidates = [
+    path.join(cwd, 'ssss'),
+    path.join(cwd, 'node_modules', '.bin', 'ssss'),
+    path.join(packageRoot, 'node_modules', '.bin', 'ssss'),
+    path.join(packageRoot, '..', '.bin', 'ssss'),
+  ];
   const tool = candidates.find(file => { try { fs.accessSync(file, fs.constants.X_OK); return fs.statSync(file).isFile(); } catch { return false; } }) || 'ssss';
   const tooling = await run(tool, ['--help'], { cwd });
   report.ssss = { status: tooling.code === 0 && !tooling.reason && /ssss/i.test(tooling.output) ? 'available' : 'unavailable', role: report.ssss.role };

package/src/core/surface.mjs

@@ -35,9 +35,10 @@ export function isSurfaceCodeStale(file = SURFACE_SOURCE, loadedHash = LOADED_SU
   try { return sourceHash(file) !== loadedHash; } catch { return false; }
 }
 
-/** Scope dirs searched for composable commands, in dispatcher order (project, then global). */
+/** Composed scope order: selected project, exact-member groups, global. */
 export function commandDirsFor(skillsDir) {
-  const dirs = skillsDir ? commandScopeDirectories(path.dirname(path.dirname(skillsDir)), globalAgentDir) : [{ scope: 'global', dir: path.join(globalAgentDir, 'commands') }];
+  const dirs = skillsDir ? commandScopeDirectories(path.dirname(path.dirname(skillsDir)), globalAgentDir,
+    { projectAgentDir: path.dirname(skillsDir) }) : [{ scope: 'global', dir: path.join(globalAgentDir, 'commands') }];
   // Compiling the global brain itself: its commands are the global ones.
   if (dirs.length === 2 && path.resolve(dirs[0].dir) === path.resolve(dirs[1].dir)) dirs.shift();
   return dirs;
@@ -399,7 +400,7 @@ export function buildInstalledPluginsSummary(projectRoot = process.cwd()) {
       const desc = (p.manifest.description || 'Plugin capability').replace(/\s+/g, ' ').slice(0, 30).trimEnd();
       const ops = (p.manifest.cli?.subcommands || []).map(sub => sub.name).filter(Boolean);
       const shown = ops.join(' | ');
-      lines.push(`- **${p.id}** v${p.manifest.version || 'unknown'} · ${pluginActivation(p).state} · \`total-recall ${cmd}\` ${shown ? `[${shown}]` : '(no operations)'}: ${desc}`);
+      lines.push(`- **${p.id}** v${p.manifest.version || 'unknown'} · ${pluginActivation(p, { projectRoot }).state} · \`total-recall ${cmd}\` ${shown ? `[${shown}]` : '(no operations)'}: ${desc}`);
     }
     return lines.join('\n') + '\n';
   } catch {
@@ -509,7 +510,7 @@ async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir
         if (!fs.statSync(target).isFile()) throw new Error('Linked instruction target must be a regular file');
         // Preserve both the link and authored target text; replace only our block.
         const raw = fs.readFileSync(target, 'utf8');
-        atomicWrite(target, injectDirectives(raw, rulesBlock));
+        writeVerifiedSurface(target, injectDirectives(raw, rulesBlock));
         return true;
       } else {
         const raw = fs.readFileSync(shimPath, 'utf8');
@@ -520,14 +521,14 @@ async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir
         }
         
         const updated = injectDirectives(cleaned, rulesBlock);
-        atomicWrite(shimPath, updated);
+        writeVerifiedSurface(shimPath, updated);
         return true;
       }
     } else {
       if (!fs.existsSync(shimDir)) {
         fs.mkdirSync(shimDir, { recursive: true });
       }
-      atomicWrite(shimPath, fullContent);
+      writeVerifiedSurface(shimPath, fullContent);
       return true;
     }
   } catch (err) {
@@ -535,6 +536,11 @@ async function writeShim(shimPath, skillsDir, nodes = [], { vaultDir, derivedDir
   }
 }
 
+function writeVerifiedSurface(file, content) {
+  atomicWrite(file, content);
+  if (fs.readFileSync(file, 'utf8') !== content) throw new Error('Instruction read-back verification failed');
+}
+
 /**
  * Map of client names → shim file paths they require.
  */
@@ -591,15 +597,39 @@ function readConnectedClients(clientsPath) {
     }
     
     return null;
-  } catch {
-    return null;
+  } catch (err) {
+    throw new Error(`Cannot read connected instruction clients: ${err.code || err.message}`);
   }
 }
 
+function instructionFiles(instructionsFile, skillsDir) {
+  const base = path.dirname(instructionsFile);
+  const agent = skillsDir ? path.dirname(skillsDir) : path.join(base, '.agent');
+  const clients = readConnectedClients(path.join(agent, 'skills', 'total-recall', 'config', 'clients.json'));
+  return [...new Set([instructionsFile, ...[...(clients || [])].flatMap(client =>
+    (CLIENT_SHIMS[client] || []).map(file => path.join(base, file)))])];
+}
+
+function describeInstruction(file, base) {
+  return { file: path.relative(base, file), target: path.relative(base, fs.realpathSync(file)), sha256: sourceHash(file) };
+}
+
+/** Derived hashes certify exact output bytes and link bindings, never runtime consumption. */
+function instructionArtifactsMatch(files, base, manifestFile) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+    if (manifest.version !== 1 || !Array.isArray(manifest.files) || manifest.files.length !== files.length) return false;
+    return files.every((file, index) => {
+      const current = describeInstruction(file, base), previous = manifest.files[index];
+      return previous?.file === current.file && previous.target === current.target && previous.sha256 === current.sha256;
+    });
+  } catch { return false; }
+}
+
 /**
  * Compile shims asynchronously.
  */
-async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultDir, derivedDir, force = false } = {}) {
+async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultDir, derivedDir, force = false, files = instructionFiles(instructionsFile, skillsDir) } = {}) {
   const agentDir = path.dirname(instructionsFile);
   // `instructionsFile` is always `<agentDir>/INSTRUCTIONS.md`, so agentDir is
   // already the directory the surface belongs in. Do not derive it again.
@@ -616,12 +646,6 @@ async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultD
   // (rebuild.mjs: `<agentDir>/INSTRUCTIONS.md` with skillsDir `<agentDir>/skills`;
   // plugin-store.mjs likewise), so the peel was never correct for either.
   const baseDir = agentDir;
-  let injectedCount = 0;
-
-  // Always write the canonical INSTRUCTIONS.md
-  if (await writeShim(path.join(baseDir, 'INSTRUCTIONS.md'), skillsDir, nodes, { vaultDir, derivedDir, force })) {
-    injectedCount++;
-  }
 
   // Determine which client shims to write.
   // `baseDir/.agent/skills/...` only holds for a PROJECT brain. For the global
@@ -631,9 +655,6 @@ async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultD
   // stopped updating. Derive the brain dir from the caller's skillsDir instead,
   // which is correct for both layers. Fall back to the legacy guess only when
   // skillsDir was not supplied.
-  const brainDirForConfig = skillsDir ? path.dirname(skillsDir) : path.join(baseDir, '.agent');
-  const clientsPath = path.join(brainDirForConfig, 'skills', 'total-recall', 'config', 'clients.json');
-  const connectedClients = readConnectedClients(clientsPath);
 
   // Client shims are written BESIDE INSTRUCTIONS.md, in the same directory, so
   // the surface directory is decided in exactly one place: `instructionsFile`.
@@ -645,20 +666,9 @@ async function compilePointers(instructionsFile, skillsDir, nodes = [], { vaultD
   // `instructionsFile`; this function must not re-derive or relocate it. Doing
   // so previously wrote every project shim into `<repo>/.agent/AGENTS.md`, where
   // no harness looks, while still reporting a successful compilation.
-  if (connectedClients !== null) {
-    // Only write shims for connected clients
-    for (const client of connectedClients) {
-      const files = CLIENT_SHIMS[client];
-      if (!files) continue;
-      for (const file of files) {
-        if (await writeShim(path.join(baseDir, file), skillsDir, nodes, { vaultDir, derivedDir, force })) {
-          injectedCount++;
-        }
-      }
-    }
-  }
+  for (const file of files) await writeShim(file, skillsDir, nodes, { vaultDir, derivedDir, force });
   
-  return injectedCount;
+  return files.length;
 }
 
 /**
@@ -709,13 +719,17 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
   // 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 inputsHash = sourceHash(SURFACE_SOURCE) + catalog.fingerprint + surfaceInputsHash({ commandDirs: commandDirsFor(skillsDir), skillsDir });
+  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) {
+    if (storedHash === currentHash && storedGlobal === globalHash && storedInputs === inputsHash &&
+        instructionArtifactsMatch(files, surfaceDir, artifactsFile)) {
       return {
         nodesProcessed: nodes.length,
         skillsInjected: 0,
@@ -728,7 +742,7 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
   }
 
   // 1. Write pointer and active rules to all instruction shims
-  const skillsInjected = await compilePointers(instructionsFile, skillsDir, ruleNodes, { vaultDir, derivedDir, force });
+  const skillsInjected = await compilePointers(instructionsFile, skillsDir, ruleNodes, { vaultDir, derivedDir, force, files });
 
   // 2. Build derived indexes (powers semantic search API)
   if (!fs.existsSync(derivedDir)) {
@@ -820,17 +834,9 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
   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);
 
-  // 6. Generate live OKF Index and Log
-  try {
-    const { generateLiveIndex, generateLiveLog } = await import('./okf-adapter.mjs');
-    generateLiveIndex(vaultDir);
-    generateLiveLog(vaultDir);
-  } catch (err) {
-    logger.warn('surface', `Failed to generate live OKF index/log: ${err.message}`);
-  }
-
   return {
     nodesProcessed: nodes.length,
     skillsInjected,
@@ -875,7 +881,8 @@ function writeProjectionManifest(derivedDir, vaultHash) {
       { file: 'local-search.json', disposable: true },
       { file: 'embeddings.jsonl', disposable: true },
       { file: 'cli-semantic-index.json', disposable: true },
-      { file: 'vault-hash.txt', disposable: true }
+      { file: 'vault-hash.txt', disposable: true },
+      { file: 'surface-artifacts.json', disposable: true }
     ],
     rebuild_command: 'npx total-recall compile'
   };