total-recall-brain 3.28.2 → 3.30.0

package/src/core/plugin-bundle.mjs

@@ -0,0 +1,167 @@
+/**
+ * Plugin bundles — the unit a node sends to a mesh peer.
+ *
+ * A bundle is plain JSON (no tar dependency) carrying every regular file of a
+ * plugin, base64-encoded, plus a SHA-256 content hash computed over a canonical
+ * ordering. The receiver recomputes the hash from the bytes it actually wrote
+ * and refuses the install on any mismatch, so a truncated or altered transfer
+ * can never become an installed plugin.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const BUNDLE_FORMAT = 'tr-plugin-bundle/1';
+export const MAX_BUNDLE_FILES = 200;
+export const MAX_BUNDLE_BYTES = 5 * 1024 * 1024;
+
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+
+/**
+ * List a plugin's files in canonical order.
+ * Dotfiles, `.git/`, `node_modules/` and symlinks are excluded: they are either
+ * local state or a way to smuggle a path outside the plugin.
+ * @returns {Array<{ path: string, abs: string, size: number, mode: number }>}
+ */
+export function listPluginFiles(pluginDir) {
+  const root = fs.realpathSync(pluginDir);
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        walk(abs);
+      } else if (entry.isFile()) {
+        const stat = fs.statSync(abs);
+        out.push({
+          path: path.relative(root, abs).split(path.sep).join('/'),
+          abs,
+          size: stat.size,
+          mode: stat.mode & 0o777
+        });
+      }
+    }
+  };
+  walk(root);
+  out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return out;
+}
+
+function hashEntries(entries) {
+  const h = crypto.createHash('sha256');
+  for (const e of entries) {
+    h.update(e.path);
+    h.update('\0');
+    h.update(String(e.data.length));
+    h.update('\0');
+    h.update(e.data);
+  }
+  return h.digest('hex');
+}
+
+/** SHA-256 over a plugin directory's canonical file list. */
+export function hashPluginDir(pluginDir) {
+  const files = listPluginFiles(pluginDir);
+  return {
+    sha256: hashEntries(files.map((f) => ({ path: f.path, data: fs.readFileSync(f.abs) }))),
+    file_count: files.length,
+    size_bytes: files.reduce((n, f) => n + f.size, 0)
+  };
+}
+
+/** Pack a plugin directory into a transferable bundle. */
+export function packPlugin(pluginDir, manifest) {
+  const files = listPluginFiles(pluginDir);
+  if (files.length > MAX_BUNDLE_FILES) {
+    throw new Error(`Plugin has ${files.length} files; the limit is ${MAX_BUNDLE_FILES}`);
+  }
+  const total = files.reduce((n, f) => n + f.size, 0);
+  if (total > MAX_BUNDLE_BYTES) {
+    throw new Error(`Plugin is ${total} bytes; the limit is ${MAX_BUNDLE_BYTES}`);
+  }
+  const entries = files.map((f) => ({ path: f.path, mode: f.mode, data: fs.readFileSync(f.abs) }));
+  return {
+    format: BUNDLE_FORMAT,
+    id: manifest.id,
+    version: manifest.version,
+    sha256: hashEntries(entries),
+    files: entries.map((e) => ({ path: e.path, mode: e.mode, data_b64: e.data.toString('base64') }))
+  };
+}
+
+function assertSafeRelativePath(p) {
+  if (typeof p !== 'string' || p.length === 0 || p.length > 512) throw new Error('Bundle file path is empty or too long');
+  if (p.includes('\\') || p.includes('\0')) throw new Error(`Bundle file path '${p}' contains a forbidden character`);
+  if (p.startsWith('/') || /^[A-Za-z]:/.test(p)) throw new Error(`Bundle file path '${p}' is absolute`);
+  const parts = p.split('/');
+  if (parts.some((s) => s === '' || s === '.' || s === '..' || s.startsWith('.'))) {
+    throw new Error(`Bundle file path '${p}' is not a plain relative path`);
+  }
+}
+
+/**
+ * Decode and check a bundle without touching the filesystem.
+ * @returns {{ id: string, version: string, sha256: string, entries: Array<{path:string, mode:number, data:Buffer}> }}
+ */
+export function decodeBundle(bundle, { expectedSha256 } = {}) {
+  if (!bundle || typeof bundle !== 'object' || bundle.format !== BUNDLE_FORMAT) {
+    throw new Error('Not a Total Recall plugin bundle');
+  }
+  if (!Array.isArray(bundle.files) || bundle.files.length === 0) throw new Error('Bundle contains no files');
+  if (bundle.files.length > MAX_BUNDLE_FILES) throw new Error('Bundle exceeds the file limit');
+
+  const seen = new Set();
+  let total = 0;
+  const entries = bundle.files.map((f) => {
+    assertSafeRelativePath(f?.path);
+    if (seen.has(f.path)) throw new Error(`Bundle lists '${f.path}' twice`);
+    seen.add(f.path);
+    const data = Buffer.from(String(f.data_b64 || ''), 'base64');
+    total += data.length;
+    if (total > MAX_BUNDLE_BYTES) throw new Error('Bundle exceeds the size limit');
+    return { path: f.path, mode: Number.isInteger(f.mode) ? f.mode & 0o755 : 0o644, data };
+  });
+  entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+  if (!seen.has('plugin.json')) throw new Error('Bundle has no plugin.json');
+
+  const sha256 = hashEntries(entries);
+  if (sha256 !== bundle.sha256) {
+    throw new Error(`Bundle content hash mismatch (declared ${bundle.sha256}, actual ${sha256})`);
+  }
+  if (expectedSha256 && sha256 !== expectedSha256) {
+    throw new Error(`Bundle content hash ${sha256} does not match the advertised ${expectedSha256}`);
+  }
+  return { id: bundle.id, version: bundle.version, sha256, entries };
+}
+
+/**
+ * Write decoded entries into `<pluginsDir>/<id>` atomically: files go to a
+ * dot-prefixed staging dir (invisible to discovery) that is renamed into place.
+ */
+export function writeEntriesAtomic(pluginsDir, id, entries) {
+  fs.mkdirSync(pluginsDir, { recursive: true });
+  const dest = path.join(pluginsDir, id);
+  if (fs.existsSync(dest)) throw new Error(`Plugin '${id}' is already installed at ${dest}`);
+  const staging = path.join(pluginsDir, `.staging-${id}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    for (const e of entries) {
+      const target = path.join(staging, ...e.path.split('/'));
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, e.data, { mode: e.mode });
+    }
+    fs.renameSync(staging, dest);
+  } catch (err) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw err;
+  }
+  return dest;
+}
+
+/** Copy a local plugin directory into `pluginsDir` atomically (same exclusions as bundles). */
+export function copyPluginAtomic(sourceDir, pluginsDir, id) {
+  const entries = listPluginFiles(sourceDir).map((f) => ({ path: f.path, mode: f.mode, data: fs.readFileSync(f.abs) }));
+  return writeEntriesAtomic(pluginsDir, id, entries);
+}

package/src/core/plugin-context.mjs

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { discoverPlugins, getPluginWatchPaths, getPlugin, getPluginCategories, validatePluginManifest } from './plugin-loader.mjs';
+import { pathToFileURL } from 'node:url';
+import { discoverPlugins, getPluginWatchPaths, getPlugin, getPluginCategories, validatePluginManifest, resolveProjectRoot } from './plugin-loader.mjs';
 
 export { discoverPlugins, getPluginWatchPaths, getPlugin, getPluginCategories, validatePluginManifest };
 
@@ -10,16 +11,7 @@ export { discoverPlugins, getPluginWatchPaths, getPlugin, getPluginCategories, v
  * Supports plugin-directed compilation via custom generators or standard SSSS category aggregation.
  */
 export async function assemblePluginContexts({ projectRoot = process.cwd(), vaultDir, nodes = [], derivedDir } = {}) {
-  let resolvedProjectRoot = projectRoot;
-  if (vaultDir && (!resolvedProjectRoot || resolvedProjectRoot === process.cwd())) {
-    try {
-      const parent = path.resolve(vaultDir, '..', '..', '..');
-      if (fs.existsSync(path.join(parent, '.agent'))) {
-        resolvedProjectRoot = parent;
-      }
-    } catch {}
-  }
-
+  const resolvedProjectRoot = resolveProjectRoot(projectRoot, vaultDir);
   const plugins = discoverPlugins(resolvedProjectRoot);
   if (plugins.length === 0) return '';
 
@@ -32,14 +24,17 @@ export async function assemblePluginContexts({ projectRoot = process.cwd(), vaul
     // 1. Check if plugin directs compilation via a custom generator
     if (manifest.compile?.generator) {
       const generatorRel = manifest.compile.generator;
-      const generatorPath = path.isAbsolute(generatorRel)
+      let generatorPath = path.isAbsolute(generatorRel)
         ? generatorRel
         : path.resolve(dir, generatorRel);
 
       if (!fs.existsSync(generatorPath)) generatorPath = path.resolve(resolvedProjectRoot, generatorRel);
       if (fs.existsSync(generatorPath)) {
         try {
-          const mod = await import(generatorPath);
+          // Keyed by mtime so an edited generator is picked up without a restart.
+          const url = pathToFileURL(generatorPath);
+          url.searchParams.set('mtime', String(fs.statSync(generatorPath).mtimeMs));
+          const mod = await import(url.href);
           const fn = mod.generateContext || mod.default;
           if (typeof fn === 'function') {
             const generated = await fn({

package/src/core/plugin-loader.mjs

@@ -1,9 +1,68 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 
 const ID_PATTERN = /^[a-z][a-z0-9-]{1,63}$/;
 const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+const USE_CASE_PATTERN = /^[a-z][a-z0-9-]{1,47}$/;
+const CRON_FIELD_PATTERN = /^[\d*,/-]+$/;
+
+/** Root of the installed total-recall package (holds `plugins/` with the bundled sources). */
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/**
+ * Where plugins live. Everything a brain owns sits under `skills/total-recall/`
+ * — `.agent/` itself holds only `skills/` and `secrets.enc`.
+ */
+export function projectPluginsDir(projectRoot = process.cwd()) {
+  return path.join(projectRoot, '.agent', 'skills', 'total-recall', 'plugins');
+}
+
+export function globalPluginsDir() {
+  const agentDir = process.env.AGENT_DIR || process.env._TR_TEST_AGENT_DIR || path.join(os.homedir(), '.agent');
+  return path.join(agentDir, 'skills', 'total-recall', 'plugins');
+}
+
+export function bundledPluginsDir() {
+  return path.join(PACKAGE_ROOT, 'plugins');
+}
+
+/** The vault that owns records for plugins installed in `pluginsDir` (`<brain>/plugins` → `<brain>/memory-vault`). */
+export function vaultForPluginsDir(pluginsDir) {
+  return path.join(path.dirname(pluginsDir), 'memory-vault');
+}
+
+/**
+ * The project a vault belongs to. A brain vault sits at
+ * `<project>/.agent/skills/total-recall/memory-vault`, four levels below the
+ * project root. Only used when the caller did not pass an explicit root.
+ */
+export function resolveProjectRoot(projectRoot, vaultDir) {
+  if (!vaultDir || (projectRoot && projectRoot !== process.cwd())) return projectRoot || process.cwd();
+  const parent = path.resolve(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. */
+export function isCronExpression(expr) {
+  if (typeof expr !== 'string') return false;
+  const fields = expr.trim().split(/\s+/);
+  return fields.length === 5 && fields.every((f) => CRON_FIELD_PATTERN.test(f));
+}
+
+/**
+ * Validates that a path is relative, normalized, and cannot traverse above its root.
+ * Rejects absolute paths, null bytes, and any use of parent directory traversal ('..').
+ */
+export function isSafeRelativePath(p) {
+  if (typeof p !== 'string' || !p.trim()) return false;
+  if (p.includes('\0')) return false;
+  if (path.isAbsolute(p) || p.startsWith('/') || p.startsWith('\\')) return false;
+  const normalized = path.normalize(p);
+  if (normalized === '..' || normalized.startsWith('..' + path.sep) || normalized.includes(path.sep + '..' + path.sep) || normalized.endsWith(path.sep + '..')) return false;
+  return true;
+}
 
 /**
  * Validates a plugin manifest object against Total Recall plugin standards.
@@ -37,6 +96,18 @@ export function validatePluginManifest(manifest) {
     errors.push("Missing required field 'description' (minimum 5 characters)");
   }
 
+  if (manifest.use_cases !== undefined) {
+    if (!Array.isArray(manifest.use_cases)) {
+      errors.push("'use_cases' must be an array of kebab-case strings");
+    } else {
+      for (const u of manifest.use_cases) {
+        if (typeof u !== 'string' || !USE_CASE_PATTERN.test(u)) {
+          errors.push(`Invalid use case '${u}': must be kebab-case`);
+        }
+      }
+    }
+  }
+
   if (manifest.ssss_schemas?.categories) {
     if (!Array.isArray(manifest.ssss_schemas.categories)) {
       errors.push("'ssss_schemas.categories' must be an array");
@@ -54,8 +125,137 @@ export function validatePluginManifest(manifest) {
       errors.push("'tasks' must be an array");
     } else {
       for (const t of manifest.tasks) {
-        if (!t.intent || !t.schedule) {
+        if (!t || !t.intent || !t.schedule) {
           errors.push("Each task must define 'intent' and 'schedule'");
+          continue;
+        }
+        if (!isCronExpression(t.schedule)) {
+          errors.push(`Task '${t.intent}' has an invalid schedule '${t.schedule}': expected 5-field cron`);
+        }
+        // A task is a plugin CLI subcommand run on a schedule. Without a
+        // command and a handler there is nothing to run, and a task that is
+        // displayed but never executes is worse than no task.
+        if (!t.command || typeof t.command !== 'string') {
+          errors.push(`Task '${t.intent}' must define 'command' (the plugin CLI subcommand to run)`);
+        }
+        if (!manifest.cli?.handler) {
+          errors.push(`Task '${t.intent}' requires 'cli.handler' to run its command`);
+        }
+      }
+    }
+  }
+
+  if (manifest.cli?.handler && !isSafeRelativePath(manifest.cli.handler)) {
+    errors.push("cli.handler must be a safe relative path without directory traversal");
+  }
+
+  if (manifest.compile?.generator && !isSafeRelativePath(manifest.compile.generator)) {
+    errors.push("compile.generator must be a safe relative path without directory traversal");
+  }
+
+  if (manifest.deploy !== undefined) {
+    if (typeof manifest.deploy !== 'object' || manifest.deploy === null) {
+      errors.push("'deploy' must be an object");
+    } else {
+      if (manifest.deploy.targets !== undefined) {
+        if (!Array.isArray(manifest.deploy.targets) || manifest.deploy.targets.length === 0) {
+          errors.push("'deploy.targets' must be a non-empty array of target names");
+        } else {
+          for (const t of manifest.deploy.targets) {
+            if (typeof t !== 'string' || !t.trim()) {
+              errors.push(`Invalid deploy target '${t}': must be a non-empty string`);
+            }
+          }
+        }
+      }
+      if (manifest.deploy.required_ssss_version !== undefined) {
+        if (typeof manifest.deploy.required_ssss_version !== 'string' || !manifest.deploy.required_ssss_version.trim()) {
+          errors.push("'deploy.required_ssss_version' must be a non-empty string");
+        }
+      }
+      if (manifest.deploy.access_grants !== undefined) {
+        if (!Array.isArray(manifest.deploy.access_grants)) {
+          errors.push("'deploy.access_grants' must be an array of permission strings");
+        } else {
+          const GRANT_PATTERN = /^[a-z0-9_-]+(:[a-z0-9_*-]+)*$/;
+          for (const g of manifest.deploy.access_grants) {
+            if (typeof g !== 'string' || !GRANT_PATTERN.test(g)) {
+              errors.push(`Invalid access grant '${g}': must follow format domain:action (e.g. ssss:vault:read)`);
+            }
+          }
+        }
+      }
+      if (manifest.deploy.adapter !== undefined) {
+        if (typeof manifest.deploy.adapter !== 'string' || !manifest.deploy.adapter.trim()) {
+          errors.push("'deploy.adapter' must be a non-empty string");
+        }
+      }
+      if (manifest.deploy.resources !== undefined) {
+        if (typeof manifest.deploy.resources !== 'object' || manifest.deploy.resources === null) {
+          errors.push("'deploy.resources' must be an object");
+        }
+      }
+    }
+  }
+
+  if (manifest.skills !== undefined) {
+    if (!Array.isArray(manifest.skills)) {
+      errors.push("'skills' must be an array");
+    } else {
+      for (const s of manifest.skills) {
+        if (!s || typeof s !== 'object') {
+          errors.push("Each entry in 'skills' must be an object");
+          continue;
+        }
+        if (!s.id || typeof s.id !== 'string') {
+          errors.push("Each skill entry must have a string 'id'");
+        }
+        if (!s.path || !isSafeRelativePath(s.path)) {
+          errors.push(`Skill '${s.id || 'unknown'}' has invalid or unsafe 'path': must be safe relative path`);
+        }
+      }
+    }
+  }
+
+  if (manifest.commands !== undefined) {
+    if (!Array.isArray(manifest.commands)) {
+      errors.push("'commands' must be an array");
+    } else {
+      for (const c of manifest.commands) {
+        if (!c || typeof c !== 'object') {
+          errors.push("Each entry in 'commands' must be an object");
+          continue;
+        }
+        if (!c.name || typeof c.name !== 'string') {
+          errors.push("Each command entry must have a string 'name'");
+        }
+        if (!c.handler || !isSafeRelativePath(c.handler)) {
+          errors.push(`Command '${c.name || 'unknown'}' has invalid or unsafe 'handler': must be safe relative path`);
+        }
+      }
+    }
+  }
+
+  if (manifest.ui !== undefined) {
+    if (typeof manifest.ui !== 'object' || manifest.ui === null) {
+      errors.push("'ui' must be an object");
+    } else {
+      if (manifest.ui.design_tokens !== undefined && !isSafeRelativePath(manifest.ui.design_tokens)) {
+        errors.push("'ui.design_tokens' must be a safe relative path");
+      }
+      if (manifest.ui.elements !== undefined && !Array.isArray(manifest.ui.elements)) {
+        errors.push("'ui.elements' must be an array");
+      }
+    }
+  }
+
+  if (manifest.openwiki_hubs !== undefined) {
+    if (!Array.isArray(manifest.openwiki_hubs)) {
+      errors.push("'openwiki_hubs' must be an array");
+    } else {
+      for (const hub of manifest.openwiki_hubs) {
+        if (!hub || !hub.path || !isSafeRelativePath(hub.path)) {
+          errors.push("Each entry in 'openwiki_hubs' must have a safe relative 'path'");
         }
       }
     }
@@ -67,75 +267,88 @@ export function validatePluginManifest(manifest) {
   };
 }
 
+/** Read and validate every `<dir>/<name>/plugin.json` under one plugins directory. */
+export function readPluginsDir(dir, scope) {
+  const out = [];
+  if (!fs.existsSync(dir)) return out;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+
+  for (const entry of entries) {
+    // Staging directories from an in-flight install are never plugins.
+    if (entry.name.startsWith('.')) continue;
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const pluginDir = path.join(dir, entry.name);
+    const manifestPath = path.join(pluginDir, 'plugin.json');
+    if (!fs.existsSync(manifestPath)) continue;
+
+    try {
+      const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      const validation = validatePluginManifest(manifest);
+      out.push({
+        id: manifest.id || entry.name,
+        manifest,
+        dir: pluginDir,
+        pluginsDir: dir,
+        manifestPath,
+        scope,
+        linked: entry.isSymbolicLink(),
+        valid: validation.valid,
+        errors: validation.errors
+      });
+    } catch (err) {
+      out.push({
+        id: entry.name,
+        manifest: {},
+        dir: pluginDir,
+        pluginsDir: dir,
+        manifestPath,
+        scope,
+        linked: entry.isSymbolicLink(),
+        valid: false,
+        errors: [`JSON parse error: ${err.message}`]
+      });
+    }
+  }
+  return out;
+}
+
 /**
  * Discover installed plugins across project and global directories.
- * Each plugin directory contains a `plugin.json` manifest.
+ * A project plugin shadows a global plugin with the same id.
  * @param {string} [projectRoot] - Current project root directory
- * @returns {Array<{ id: string, manifest: object, dir: string, manifestPath: string, valid: boolean, errors: string[] }>}
  */
 export function discoverPlugins(projectRoot = process.cwd()) {
+  const seen = new Set();
   const plugins = [];
-  const searchDirs = [
-    path.join(projectRoot, '.agent', 'plugins'),
-    path.join(os.homedir(), '.agent', 'plugins')
+  const sources = [
+    [projectPluginsDir(projectRoot), 'project'],
+    [globalPluginsDir(), 'global']
   ];
-
-  const seenIds = new Set();
-
-  for (const dir of searchDirs) {
-    if (!fs.existsSync(dir)) continue;
-    let entries = [];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-      const pluginDir = path.join(dir, entry.name);
-      const manifestPath = path.join(pluginDir, 'plugin.json');
-
-      if (fs.existsSync(manifestPath)) {
-        try {
-          const raw = fs.readFileSync(manifestPath, 'utf8');
-          const manifest = JSON.parse(raw);
-          const validation = validatePluginManifest(manifest);
-          const id = manifest.id || entry.name;
-
-          if (!seenIds.has(id)) {
-            seenIds.add(id);
-            plugins.push({
-              id,
-              manifest,
-              dir: pluginDir,
-              manifestPath,
-              valid: validation.valid,
-              errors: validation.errors
-            });
-          }
-        } catch (err) {
-          // Record unparseable manifest
-          const id = entry.name;
-          if (!seenIds.has(id)) {
-            seenIds.add(id);
-            plugins.push({
-              id,
-              manifest: {},
-              dir: pluginDir,
-              manifestPath,
-              valid: false,
-              errors: [`JSON parse error: ${err.message}`]
-            });
-          }
-        }
-      }
+  const visited = new Set();
+  for (const [dir, scope] of sources) {
+    const resolved = path.resolve(dir);
+    // When the project *is* the home brain the two directories coincide.
+    if (visited.has(resolved)) continue;
+    visited.add(resolved);
+    for (const p of readPluginsDir(dir, scope)) {
+      if (seen.has(p.id)) continue;
+      seen.add(p.id);
+      plugins.push(p);
     }
   }
-
   return plugins;
 }
 
+/** Plugins shipped inside the total-recall package, installable on any node. */
+export function listBundledPlugins() {
+  return readPluginsDir(bundledPluginsDir(), 'bundled');
+}
+
 /**
  * Retrieve a specific plugin by id.
  */
@@ -174,16 +387,7 @@ export function getPluginCategories(projectRoot = process.cwd()) {
  * Collect all filesystem paths watched by installed plugins for plugin-directed compilation.
  */
 export function getPluginWatchPaths(projectRoot = process.cwd(), vaultDir) {
-  let resolvedProjectRoot = projectRoot;
-  if (vaultDir && (!resolvedProjectRoot || resolvedProjectRoot === process.cwd())) {
-    try {
-      const parent = path.resolve(vaultDir, '..', '..', '..');
-      if (fs.existsSync(path.join(parent, '.agent'))) {
-        resolvedProjectRoot = parent;
-      }
-    } catch {}
-  }
-
+  const resolvedProjectRoot = resolveProjectRoot(projectRoot, vaultDir);
   const plugins = discoverPlugins(resolvedProjectRoot);
   const paths = new Set();